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STUDENT GUIDE 



INTRODUCTION 

Programming RSX-11M in FORTRAN is intended for FORTRAN programmers 
who use services of the RSX-11M operating system beyond those 
provided by the FORTRAN programming language itself. This course 
describes the various services and how to use them from a task 
which you wr i te . 

This course is self-paced, which means that you learn at whatever 
rate is comfortable for you. 

Instead of a teacher, you have a course administrator and a 
subject matter expert. In some cases, the same person can perform 
both functions. The course administrator manages the mechanics of 
the course and makes sure you have easy access to the system and 
the on-line course materials. As you finish modules, s/he records 
your progress. The subject matter expert helps you if you have a 
technical question. Before you consult the expert, however, read 
the course materials and references in an effort to answer the 
question yourself. 

This Student Guide covers the following topics: 



• 


Course 


prerequisites 


• 


Course 


goals (and nongoals) 


• 


Course 


organi zation 


• 


Course 


map description 


• 


Course 


resources 


• 


How to 


take the course 


• 


Personal Progress Plotter 
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PREREQUISITES 

To be prepared for this course, you must have taken the following 
DIGITAL courses, or you must have equivalent experience, 

1. RSX-11M Utilities and Commands. Specifically, you must be 
able to logon/logoff, edit files, and develop/run/debug 
programs under RSX-11M. 

2. Programming in FORTRAN. 

COURSE GOALS AND NONGOALS 



On completion of this course, you should be able to write tasks 



which : 






1. 


Use executive directives 




2. 


Perform intertask communication and 


coordination 


3. 


Perform synchronous and asynchronous 


I/O operations 


4. 


Use overlays 




5. 


Use memory management facilities to 
tasks and make more effective use of 


communicate between 
available memory 


This course does not teach the following: 




1. 


The FORTRAN programming language 




2. 


The Digital Command Language (DCL) 
Routine (MCR) 


or Monitor Console 


3. 


The program development cycle. 
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COURSE ORGANIZATION 

This course is self-paced for independent study. The course 
material is structured in modules. Each module is a lesson on one 
or more skills required to fulfill the course goals. A module 
consists of: 

• An introduction to the subject matter of the module 

• A list of objectives, which describe what you should 
achieve by studying the module 

• A list of resources that provide reference materials and 
additional reading for the module 

• The module text, including explanatory text, figures, 
tables, examples, and references to readings in the 
manuals 

• Learning activities (for some modules) , consisting of 
reading assignments or written exercises which are 
essential to your learning the material 

• Written and/or lab tests/exercises (bound separately) 
which you can use to measure your achievement. Solutions 
are provided for all exercises. 

The course is bound in three volumes. The first two volumes 
contain this student guide, the 10 modules (except for their 
tests/exercises), and the appendices. The third volume contains 
the tests/exercises for each module. 



COURSE MAP DESCRIPTION 

The course map shows how each module relates to the other modules 
and to the course as a whole. Before beginning a specific module, 
it is recommended that you first complete all modules with arrows 
leading into that module. These prerequisite modules present 
material necessary to understanding the module you are about to 
study. 

If you have no preference, study the modules in numerical order, 1 
through 10. 
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COURSE MAP 




TK-7749 



6 



STUDENT GUIDE 



COURSE RESOURCES 

Required References 

1. RSX-11M/M-PLUS Executive Reference Manual ( AA-L675A-TC) 

2. RSX-11M/M-PLUS I/O Drivers Reference Manual (AA-L677A-TC) 

3. RSX-11M/M-PLUS Task Builder Manual (AA-L680A-TC) 

Optional References 

1. PDP-11 Processor Handbook (EB-19402-20/81) 

2. FORTRAN IV User's Guide 

3. FORTRAN IV-PLUS User's Guide 

4. FORTRAN 77 User's Guide 
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HOW TO TAKE THE COURSE 

Because this is a self-paced course, you determine how much time 
to devote to each subject. You can pass quickly over familiar 
topics. You can spend more time on topics which are of interest 
to you, or which you can use often in your job, and less time on 
topics which have little use in your job. 

Each time you are ready to begin a new module, first read the 
introduction and the objectives. If you feel that you already 
understand the material in the module, you can go immediately to 
the tests/exercises for that module. If you don't understand much 
of the material, read the module. If you understand some of the 
concepts but not others, just look over the program examples for 
the concepts you understand. Read the text and study the examples 
for concepts you don't understand. The text explains new concepts 
and refers you to related readings in the manuals. The program 
examples provide working examples which show you how to apply the 
concepts. 

Some of the readings in the manuals are required and others are 
optional. Required readings are contained in learning activities 
and are indented to set them apart from the module text. These 
readings are required because they cover material not otherwise 
covered in this course. The optional readings are mentioned 
within the module text and are designed to help you in two ways. 
First, they teach you more about a given topic. Second, they 
offer another explanation in case you have trouble understanding 
the explanation in this course. 

In addition, you will need the manuals to look up the specifics 
involved in invoking the various services. This is especially 
true for the executive directives. 

Keep the module objectives in mind. If a skill is listed as an 
objective, be sure to master it. Later modules may depend on this 
skill. 

The module text contains many example programs to show you how to 
use the skills you are learning. All of the example programs in 
this book should be available on-line. The standard location for 
these files is UFD [202,1] on your system disk. Check your system 
and if the files are not located there, check with your course 
administrator to find out where they are located. 
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Do not modify the files in UFD [202,1] or in their original 

location. Instead, copy the files you plan to use to your own UFD 

and use them there. In that way, the original files in UFD 
[202,1] will remain intact for other students. 

Each example program contains the following: 

• Source code 

• A sample run session 

• Bulleted items which are described in the text. 

The source code contains the name of the file which contains the 
code on-line. Following this is a brief description, telling what 
the example does. Any special compile and task-build 
instructions, and any special install and run instructions follow 
this. Only special, nonstandard instructions are included. The 
code itself includes line comments plus some additional comments. 

The sample run session shows what happens during a typical run of 
the task. Any special install and run instructions are shown in 
the run session. 

The bulleted items match the example notes in the text, which 
describe the code in more detail. Study the examples and the 
notes that describe them carefully. 

In the module on Using File Control Services, many of the examples 
create output files. A dump of any created file follows the run 
session. The file dumps were created using the DMP utility. 

If the examples are available on-line, compile and task-build 
them, and then run them. This will help you to understand the 
examples better. Many of the tests/exercises ask you to make 
minor changes to existing examples, and then run them again. Do 
the tests/exercises for a module in the Tests/Exercises book only 
after you have done all of the reading and have run the example 
programs. If you prefer, you can do them as soon as you cover the 
necessary material in the module. 

The same Tests/Exercises book is used in this course and the 
Programming RSX-11M in MACRO course. Do all tests/exercises 
except those which specifically say "in MACRO". All exercises 
have solutions in the Tests/Exercises book. In addition, any 
solutions involving programs should be available on-line, in UFD 
[202,2] . Compare these solutions to your own. 
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If you have mastered the module objectives, ask your course 
administrator to record your progress on your Personal Progress 
Plotter. You will then be ready to begin a new module. If you 
haven't yet mastered the module objectives, return to the module 
text for further study. 

With a self-paced course, it is impossible to give a schedule that 
applies to all students. The amount of time that students spend 
on a module depends on both their experience and their interest in 
the topics in that module. Use Table 1 as a guide when you set 
your schedule. 
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In addition to the 10 modules, the Student Workbook contains 
several appendices. These are: 

Appendix A - Glossary 

Appendix B - Conversion Tables. This appendix contains a 
table for converting between decimal and octal, and among 
words, bytes, and memory blocks. It also contains a table 
for converting from active page registers (APRs) to virtual 
addresses . 

Appendix C - F0RTRAN/MACR0-1 1 Interface. This appendix 
contains an explanation of the techniques which you should 
use to write a FORTRAN callable subroutine in MACRO. It also 
explains how to call such a subroutine from FORTRAN. 

Appendix D - Privileged Tasks. This appendix contains a 
description of the various types of privileged tasks 
supported under RSX-11M, and how to create them. 

Appendix E - Task Builder Use of Psect Attributes. This 
appendix contains a description of the effect of Psect 
attributes on how the Task Builder collects together 
scattered occurrences of program sections. 

Appendix F - Additional Shared Region Topics. This appendix 
contains several additional shared region topics. They are: 
overlaid shared regions, referencing multiple regions from a 
single task, interlibrary calls, and cluster libraries. 

Appendix G - Additional Example. This appendix contains the 
source code for any program examples which are required for 
the Tests/Exercises but are not included elsewhere in the 
Student Workbook. These examples should also be available 
on-line, under UFD [202,1]. They are included here in case 
they are not available on-line on your system. 

Appendix H - Learning Activity Answer Sheet. This appendix 
contains the solutions to any Learning Activity questions in 
this course. After you do a Learning Activity, check your 
answers against those provided. 
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Table SG-1 Typical Course Schedules 



More Experienced Less Experienced 

Module Student Student 



1. 


Using System 
Services 


2.0 


hours 


3.0 


hours 


2. 


Di rectives 


5.0 


hours 


7.5 


hours 


3. 


Using the QIO 
Directive 


4.0 


hours 


6.0 


hours 


4. 


Using Directives 
for Intertask 
Communication 


5.0 


hours 


7.5 


hours 


5. 


Memory Management 
Concepts 


2.0 


hours 


3.0 


hours 


6. 


Overlays 


5.0 


hours 


7.5 


hours 


7. 


Static Regions 


4.5 


hours 


7.0 


hours 


8. 


Dynamic Regions 


4.5 


hours 


7.0 


hours 


9. 


File I/O 


2.0 


hours 


3.0 


hours 


10. 


File Control 
Services 


6.0 


hours 


9.0 


hours 



Totals 40.0 hours of 60.5 hours of 

study and lab study and lab 
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PERSONAL PROGRESS PLOTTER 



MODULE 


n atp 

UH 1 C 

STARTED 


UA 1 t 

COMPLETED 


1 NVI C 

SPENT 


olOIM-Ur r 

INITIAL 


1. Uol IMvj oTol fclvl 

SERVICES 










2. DIRECTIVES 










3. USING THE QIO 
DIRECTIVE 










4. USING DIRECTIVES 
FOR INTERTASK 
COMMUNICATION 










5. MEMORY 

MANAGEMENT 
CONCEPTS 










6. OVERLAYS 










7. STATIC REGIONS 










8. DYNAMIC REGIONS 










9. FILE I/O 










10. FILE 

CONTROL 
SERVICES 
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INTRODUCTION 



RSX-11M provides system services which perform many operations 
commonly needed by user-written application programs. Use of 
these services can: 

• Improve the efficiency of your tasks by reducing the size 
and execution time 

• Decrease the time it takes to code and debug your tasks 

• Increase the reliability of your task 

• Provide you with controlled access to system features 

• Improve the overall performance of your system 



This module discusses what services exist and how they are called 
from a task. 



1. Identify the facilities provided through system services. 

2. List the various system libraries and the facilities they 



OBJECTIVES 



provide . 



RESOURCES 



1. 



RSX-11M/M-PLUS Executive Reference Manual , Chapter 1 



2. 



FORTRAN IV User' 



s Guide , Appendix B 



3. 



FORTRAN IV-PLUS User 1 



s Guide , Appendix D 



4. 



FORTRAN-77 User's Guide , Appendix D 
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WHAT IS A SYSTEM SERVICE? 

An RSX-11M system service is a function or service performed for a 
running task during the task's execution. The software which 
provides the service is either in the Executive or in other system 
supplied code. 



WHY SHOULD YOU USE SYSTEM SERVICES? 



To Extend the Features of Your Programming Language 

System services offer you additional features not inherently part 
of your programming language. Examples of this are: 

• Accessing shared resources in a properly synchronized way 

• Coordinating multiple tasks 

• Controlling memory allocation and mapping 

• Interacting with the Executive 



To Ease Programming and Maintenance 

DIGITAL provides the code to perform these services, hence less 
time is needed for the user to develop working programs. The 
supplied code has a well defined modular structure which eases 
user design for his programs. 

The code for system services is well debugged. This makes it 
easier to debug and maintain programs, since there are fewer 
potential points of failure and only the user written code needs 
to be debugged. When maintenance is required in the code for the 
supplied system services, patches are released by DIGITAL with 
clear-cut installation procedures. 
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To Increase Performance 

The supplied code to perform system services is generally written 
in MACRO-11 which assures minimum execution time. It is often 
possible to share the code among several different tasks, with 
minimal additional overhead. This can result in any or all of the 
following performance gains: 

Increase in your task's throughput 

Increase in your system's throughput 

Increase in memory usage efficiency on your system 

Decrease in your task's size 

Increase in available space on mass storage volumes 



WHAT SERVICES ARE PROVIDED? 

The system services can be divided into a number of classes. For 
each, a few examples are mentioned to give you a feeling for the 
kinds of services available. 

Note that a number of the services provided to tasks parallel 
those provided to operators through DCL commands. 

System and Task Information 

You can obtain information from the system. For example, you can: 

• Obtain information about your task 

its priority 

its logical unit (LUN) assignments 

• Obtain information about a partition on the system 

its base address 
- its length 

• Obtain the current time and date 
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Task Control 

You can start up and stop tasks, and alter task states. For 
example, you can: 

• Request another task to run 

• Abort a task 

• Suspend or resume a task 

• Alter the running priority of an active task 



Task Communication and Coordination 



You can create a set of tasks that 
and coordinate the interaction 
can : 



communicate with one another 
of the tasks. For example, you 



• Send data from one task to another 

• Have one task notify other tasks that an event has 
occurred (e.g., that a job has been completed) 

• Have one task pass a command to another task and have it 
obtain an indication from the other task about the status 
of the execution of the command. 



I/O to Peripheral Devices 

You can interact with peripheral devices on your system. For 
example, you can: 

• Perform special I/O functions which cannot be accomplished 
by FORTRAN READ or WRITE statements such as reading from a 
terminal with the NOECHO feature invoked. 

• Attach a device for exclusive use by a task 

• Read or set variable characteristics of a device (e.g., 
for a terminal - baudrate or hold screen mode) 
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Memory Use 

You can use system services to control the amount of memory your 
task uses or to permit several tasks to share an area of memory. 



For example, you 


• 


Run a ta 




overlays 


• 


Allocate 




then re 




finished 


• 


Share a 


• 


Share a 




-subrouti 



Share a data area in memory among several tasks 



OTHER SERVICES AVAILABLE 

You can use system services to perform often needed functions. 
For example, you can: 

• Convert between Radix-50 and ASCII format 

• Get the date in dd-mon-yr format or as three integers 

These services are generally supplied as subroutines located in 
the system object library (LB: [1 , 1] SYSLIB.OLB) . 
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HOW SERVICES ARE PROVIDED 

When a system service is needed in a task, it is called via the 
CALL statement just as for any other subroutine. Services are 
provided using two different methods: 

1. The Executive is invoked by the task to perform the 
service (an executive directive) 

2. The code to perform the service is placed directly into 
the task 



Executive Directives 

Figure 1-1 shows how the first method works. The following steps 
are involved: 

Q The user task makes a service request and invokes the 
Executive 

Q The Executive takes control and performs the service 

Q The Executive returns control to the user task, at the 
statement following the service request. 

Figure 1-2 shows a more complex version of the first method. In 
this case task A and task B use a system service to interact 
through the Executive. 

Task A starts up and at some point needs task B to do some work; 
possibly a calculation. Task A sends the data to task B, requests 
task B to run, and then waits until task B sends back the answer. 
Task B starts running, performs the calculation, and then sends 
the answer back to task A. Task B also notifies task A that the 
job is finished. Task A then starts up again and uses the answer. 
The steps outlined above for method one would actually be used a 
number of times in this example. 
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EXECUTIVE 



I/O 

DRIVERS 



CODE TO 
SERVICE 
EXECUTIVE 
DIRECTIVE 



— F11ACP 
-♦OTHER TASKS 



TASK 

A EXECUTIVE DIRECTIVE 
INVOCATION 









Q RETURN OF 
STATUS FROM 
EXECUTIVE 



ure 1-1 Using Executive Directives to Service a Ta 
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EXECUTIVE 



CODE TO 
SERVICE 
DIRECTIVES 
I 1 

1 M 1 



TASK A 



EXECUTIVE DIRECTIVES 



RESULTS FROM 
TASK B 



I DATA FROM TASK A I 

T 



TASK B 



EXECUTIVE DIRECTIVES 



Figure 1-2 Using Executive Directives to Receive Services 

From Other Tasks 
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Code Inserted into Your Task Image 

The second method of providing system services is illustrated in 
Figure 1-3. The code to perform the service is inserted directly 
into the user task. For system subroutines, the subroutine call 
results in a transfer of control to the subroutine code, located 
in another part of the user task. 



Certain services must be provided by invoking the Executive. Any 
service which involves synchronization or access to shared 
resources must be coordinated by the Executive. For example, if a 
request activates another task, the Executive must enter the task 
in the active task list, which sets the task up to compete for 
memory space and then CPU time. It is much easier to have the 
Executive coordinate all the tasks, rather than require that each 
task check with every other task before using a shared resource. 
Also, any activity that involves communication or coordination 
among multiple tasks usually must be performed by the Executive. 

Placing the code in the user task is appropriate for a service 
which is performed independently by a task. For example, if a 
task converts an ASCII decimal value which is input at a terminal 
to a Radix-50 value for internal use, there is no need for the 
Executive to coordinate that activity. It does not affect shared 
resources or other tasks. 



If a service can be provided without need for the Executive, and 
that service is needed often by a number of different tasks, it is 
possible to share one copy of the code among several tasks. Using 
special techniques, often used subroutines can be collected and a 
single copy of each subroutine can be shared in memory among 
several tasks. The procedure for producing and using a shared 
collection of subroutines, called a resident library, is discussed 
in the Static Regions module of this course. 

Some of the services covered in this course are provided by making 
special requests when you task-build your task. In some cases, 
the Task Builder transparently places code directly in your user 
task. In other cases, it sets your task up in a special way to 
provide the service. We will discuss the techniques for accessing 
services with the Task Builder in later modules. 
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FROM SYSTEM OBJECT 
LIBRARY OR FORTRAN 
OBJECT TIME SYSTEM 
LIBRARY AT TASK-BUILD 
TIME 

TK-9387 



Figure 1-3 Code Inserted into Your Task Image 



TASK 



SUBROUTINE CALL 



SUBROUTINE ENTRY 

POINT 

RETURN 



27 



USING SYSTEM SERVICES 



AVAILABLE FILE AND RECORD ACCESS SYSTEMS 

There are two file and record access systems available under 
RSX-11M, File Control services (FCS) and Record Management 
Services (RMS). Both offer an interface between tasks and the 
Files-11 structure used to maintain disk directories and files, 

FCS is the standard access system supplied with RSX-11M. Many of 
the utilities (e.g., PIP, EDT, and the Task Builder) use FCS for 
their file interface. RMS offers all of the FCS functionality 
plus additional capabilities not available with FCS, such as 
indexed files and more sophisticated file sharing. 

While it is transparent to the FORTRAN user, all READ or WRITE 
statements ultimately result in calls to various FCS or RMS 
subroutines. 



SYSTEM LIBRARIES 

Table 1-1 contains a list of the libraries which are used during 
program development of a task using system services. They are 
usually located in LB: [1,1]. SYSLIB.OLB is the system object 
library searched by default by the Task Builder. 
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Table 1-1 Standard Libraries 



Langages Version of Contents Notes 

Using FORTRAN Using 

Library Library 



SYSLIB. 


OLB 


FORTRAN 


Executive directive 


Default object 








calls for FORTRAN 


library for 










Task Builder 








FCS subroutines 










Other file access 










routines 










Command retrieval 










and parsing 










routines 










Assorted conversion 










routines, arithmetic 










routines, memory 










management routines 




RMSLIB. 


OLB 


FORTRAN 


RMS subroutines 








indirectly 










used 






FOROTS. 


OLB 


FORTRAN IV 


FORTRAN IV Object 


Optional soft- 








Time System (OTS) 


ware may be 










included in 










SYSLIB. OLB 


F4P0TS. 


OLB 


FORTRAN IV- PLUS 


FORTRAN IV-PLUS OTS 


Optional soft- 






FORTRAN-77 


FORTRAN-77 OTS 


ware may be 










included in 










SYSLIB. OLB 
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One or the other of the last two libraries must be included when 
task-building a FORTRAN task unless, as the note states, the 
libraries are included in SYSLIB.OLB. 

Check with your system manager to determine what additional 
software may be included in SYSLIB.OLB at your site. 

Table 1-2 contains a list of the shareable resident libraries 
which may also be on your system depending upon your installation. 
You will learn how to use these resident libraries in Module 7, 
the Static Regions module. Check with your system manager to find 
out whether the preferred method of including these routines is 
through linking the code into your task image or through using the 
resident libraries. 



Table 1-2 Resident Libraries 



Resident 
Library 


Routines 
Extracted From 


Notes 


FCSRES.TSK 


SYSLIB.OLB 


Generally contains most 
FCS routines 


FORRES. TSK 
F4PRES . TSK 


FOROTS . OLB 
F4P0TS. OLB 


May contain all or 

some FORTRAN OTS routines 


RMSRES . TSK 


RMSLIB . OLB 


Full-functionality RMS 
resident library 


RMSSEQ. TSK 


RMSLIB . OLB 


RMS resident library for 
sequential access only 



Now do the Tests/Exercises for this module in the Tests and 
Exercises Book. They are all written problems. Check your 
answers against those provided in that book. 

If you think that you have mastered the material, ask your course 
administrator to record your progress in your Personal Progress 
Plotter. You will then be ready to begin a new module. 



If you think that you have not yet mastered the material, return 
to this module for further study. 
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INTRODUCTION 

As stated in the previous module, system services can be placed 
into two groups: 

• Those which are handled entirely by the user task (via the 
subroutine representing the service) 

• Those which require the intervention of the Executive 

The services in the second group are known as executive directives 
(directives) . This module discusses the services available as 
directives and how to make various directive calls. 

OBJECTIVES 

1. To write programs in FORTRAN which use directives 

2. To use information returned by the Executive to perform 
error checking 

3. To use event flags and ASTs with directives 

RESOURCES 

1. RSX-11M/M-PLUS Executive Reference Manual , Chapters 1 and 
2 plus specific directives in Chapter 5 

2. FORTRAN IV User's Guide , Appendix B 

3. FORTRAN IV-Plus User's Guide , Appendix D 

4. FORTRAN 77 User's Guide , Appendix D 
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INVOKING EXECUTIVE DIRECTIVES FROM A USER TASK 



Directive Processing 

When an executive directive is called from a FORTRAN task, a 
standard CALL is generated with an argument list containing each 
argument in the CALL. When the Task Builder builds the task, the 
code for the subroutine which invokes the directive is placed in 
the task. (The subroutines are found in LB: [1, 1] SYSLIB. ) 

At execution time this code generates a Directive Parameter Block 
(DPB) and then pushes the DPB onto the stack. The DPB contains 
all of the information needed by the Executive to perform the 
requested service. This includes a Directive Identification Code 
(DIC) which identifies which directive is being requested and the 
length of the DPB. The length is included because the length can 
vary depending on what directive is being called. 

At execution time, the following steps occur: 

• The DPB is pushed onto the stack and a trap is made to the 
Executive. 

• A dispatcher routine (part of the Executive) receives the 
DPB and determines which directive has been requested. 

• The dispatcher routine enters the Executive at the 
appropriate point, depending on the DIC, and the Executive 
executes the code for the directive (note that the code for 
the directive actually resides in the Executive, not in the 
task) . 

• The Executive sends a Directive Status Word to the task and 
then returns control to the user task. 

Most directives pass control back to the user task at completion 
of the directive. Certain directives by their nature do not 
return to the user task. For instance, the Exit Task directive 
causes the task to EXIT. For the Exit Task directive and other 
directives of this type, control passes back to the user task only 
if an error occurs in issuing the directive. 
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Functions Available Through Executive Directives 

Table 2-1 lists many of the Executive directives which are 
available on your system. For a complete list of the directives 
under each group, see section 5.1 (on Directive Categories) in the 
RSX-11M/M-PLUS Executive Reference Manual . 

This module, along with later modules on Using the QIO Directive, 
Using Directives for Intertask Communication, and Dynamic Regions 
introduce many of the functions which are available. No attempt 
is made to go over every executive directive. However, at the end 
of this course, you should know how look up any directive in the 
manual and invoke it. Each directive is documented individually 
in Chapter 5 of the RSX-11M/M-PLUS Executive Reference Manual . 
The directives appear there in alphabetical order by MACRO-11 
name; the FORTRAN CALL name for directives is similar to the 
MACRO-11 name and is also included in the list. A condensed list 
of the MACRO and FORTRAN directive names also exists in Table 1-1 
in section 1.5.2. To find the page reference for a particular 
directive, look under "CALL" in the index. 
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Table 2-1 Types of Directives 



Type 


CALL Name 


Description 


Task Execution 


ABORT 


Abort task 


Control 


EXIT 


Exit task 




REQUES 


Request task 




RESUME 


Resume task 




RUN 


Run task 




bTART 


Run task 




SUSPND 


Suspend task 




STOP 


Stop task 




USTP 


Unstop task 


Task Status 


ALTPRI 


Alter priority 


Control 


DISCKP 


Disable checkpointing 




ENACKP 


Enable checkpointing 


Informational 


GETPAR 


Get partition parameters 




Several 


Get time parameters 


Event- 


CLREF 


Clear event flag 


Associated 


CRGF 


Create group global flags 




ELGF 


Eliminate group global flag; 




MARK 


Mark time 




WAIT 


Mark time 




READEF 


Read all event flags 




READEF 


Read extended event flags 




bE 1 hi? 


Set event flag 




WAITFR 


Wait for single event flag 


Trap— Associated 


C D T? A 


Specify requested exit AST 


I/O and 


ASNLUN 


Assign LUN 


Intertask 


QIO 


Queue I/O request 


Communications 


WTQIO 


Queue I/O request and wait 




RECEIV 


Receive data 




SEND 


Send data 


Memory 


CRRG 


Create region 


Management 


MAP 


Map address window 


Parent/ 


EXST 


Exit with status 


Offspring 


SPAWN 


Spawn task 



Tasking 
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The Directive Status Word (DSW) 

Upon completion of directive processing, the Executive returns a 
code in the Directive Status Word (DSW) which gives the status of 
the request. In order to examine the contents of the DSW and 
hence determine success or failure, a specific argument must be 
included in the CALL for the directive. This argument is always 
the last argument in the list. While this argument is optional, 
it should always be included since examining the DSW is the only 
way to determine the success or failure of a directive. The 
system does not look on a directive failure as an error; hence it 
is up to the user to check the DSW after a directive CALL. The 
variable name " IDSW" is frequently used for the DSW; it must be 
an integer variable. 

Successful completion is usually indicated by a DSW value of +1. 
A negative value indicates an error. Different negative values 
correspond to different reasons for errors. These values and 
their general meanings appear in Appendix B of the RSX-11M/M-PLUS 
Executive Reference Manual and in the RSX-11M/M-PLUS Executive 
Reference Manual . Specific error values and any special meanings 
are documented with each executive directive call in Chapter 5 of 
the RSX-11M/M-PLUS Executive Reference Manual . 

See Example 2-1 for an illustration of how to use the DSW. 
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Sample Program 

Example 2-1 illustrates the use of the Request Task and the Exit 
Task directives. The directives are given below, along with a 
description of their functionality: 

The Exit Task Directive 

format: CALL EXIT - this CALL has no arguments 

- used to make a task inactive and to free up the system 
resources it uses 

The Request Task Directive 

- format: CALL REQUES (TASKNM, , IDSW) where TASKNM is the 
name of the task to be requested 

used to request the specified installed task 

this directive offers the same functionality as the DCL 
RUN command for an installed task 

Each program example in the course contains the following: 

• Source code 

• A sample run session 

• Bulleted items which are described in the text 

See the Student Guide for additional information on how to use the 
examples . 
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The following comments are keyed to Example 2-1. 

O If the appropriate OTS library has been included in 
SYSLIB, the reference to the OTS library is dropped. 

O Invoke the Request Task directive. Note that the six 
character (or less) task name must be provided in Radix-50 
format. This is accomplished by using the R (Radix-50) 
data type in the DATA statement. (Radix-50 is a method of 
representing a limited set of ASCII characters, such that 
three characters can be packed into a single PDP-11 word.) 
The task name must be the installed name (...PIP), not 
just PIP. 

The task is always assumed to be six Radix-50 characters; 
hence you should always pad a name of less than six 
characters with trailing blanks. For instance, TASKNM 
6R/ABC / should be used rather than TASKNM 3R/ABC/. 

See Appendix A of the Language Reference Manual for 
additional information on Radix-50. 

O The only case in which control will return to the user 
task after a CALL EXIT is when an error occurred in 
issuing the directive. 

O l n case of an error, display a message and the DSW value. 

O A run session is provided for each example program. Note 
that the PROGRAM name is REKWST, not REQUES. REQUES 
cannot be used because it is the name of a directive. 
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PROGRAM REKUIST 

C 

C FILE REQUES ♦ FTN 
C 

C This task displays a message y reauests PIPy and 

C then exits 

C 

C Task-build instructions* 
C 

"C If your LBtClriDSYSLIEUOLB does not contain the 

C FORTRAN Object Time System)' then you must 

C specify the appropriate object library 

C 

C With FORTRAN IVi 

C 

C L INK/MAP REQUES y LB tl 1 ? 1 ."J FOROTS/L I BR AR Y 

C 

C With FORTRAN IV-PLUS and FORTRAN-77 

C 

C >L INK/MAP/CODE I FPP REQUES y LB I I 1 y 1 3F4P0TS- 

C ->/L.l'BRARY 

C ! /CODE* FPP includes space in the task 

C ! header for savins! the state of the 

C ! floating point processor* 

„C 

"C Data statement for RAD50 task name 

DATA TASKNM /6R * * *PIP/ 
Display startup text 

WRITE <5f50) 

SO FORMAT (' REQUES HAS STARTED AND WILL REQUEST PIP') 

"CALL REQUES ( TASKNM y y IDS W ) 
C Check for Directive error 

IF (IDSW *NE* 1) GOTO 1000 
C No error y so exit 

CALL EXIT 

C Error code* Display error message and then exit* 
1000 WR I TE ( 5 y 1 1 ) I DS W 

1010 FORMAT (' ERROR REQUESTING TASK* IDSW '»I5> 
CALL EXIT 
END 



Run Session 



>RUN REQUES 

REQUES HAS STARTED AND WILL REQUEST PIP 
PIP>~Z 



Example 2-1 Requesting a Task From Another Task 
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Example Using Other Directives 

The following directives are used in Example 2-2. 
Suspend Task (CALL SUSPND) 

• Used to suspend the issuing task 

• The task can be resumed by another task issuing a resutne 
task directive or by an operator using the DCL CONTINUE 
command . 

Alter Priority (CALL ALTPRI) 

• Alters the running priority of an active task. 
Disable Checkpointing (CALL DISCKP) 

• Disables checkpointing for a checkpointable task. 
Enable Checkpointing (CALL ENACKP) 

• Enables checkpointing again after a DISCKP directive. 
Extend Task (CALL EXTTSK) 

• Modifies the size of the task by an increment or decrement 
of 32-word blocks. 
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Example 2-2 shows the use of a variety of directives. See the run 

demonstration below the source code. The following comments are 

keyed to the example. Items 2,3,5 and 7 refer to the run session 
following the program listing. 

Task suspends itself. This allows the operator to use the 
DCL SHOW TASKS/ACTIVE command to examine the task 
parameters . 

Note that the task is loaded at addresses 01123600(8) to 
01170100(8). SPN means the task is suspended. 

The operator must use the DCL CONTINUE command to resume 
the task. 

O Suspend again after disabling checkpointing and altering 
the running priority. 

Note the change in PRI (running priority) . CKD in the 
output from the DCL command SHOW TASKS/ACTIVE indicates 
that checkpointing has been disabled. 

Suspend again after enabling checkpointing, altering the 
priority back to 50(10), and extending the task. 

Note the change in priority. Note also that the task was 
checkpointed and is now loaded at addresses 01123600(8) to 
01210100(8). This is a task size of 64300(8) bytes, 
compared to 44300(8) bytes before. The extend is for 
200(8) blocks, where each block is 100(8) bytes long, 
meaning 20000(8) bytes extra. See Appendix B for a 
conversion table for bytes to blocks and of octal to 
decimal. 

01170100(8) 01210100(8) 
-01123600(8) -01123600(8) 



44300(8) 64300(8) 
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PROGRAM MISC 

Of 

C FILE MISC*FTN > 
C 

C This task uses some miscellaneous Executive directives 
C to suspend itself? alter its running priority* disable 
C and enable checkpointing* and extend its task size* 
C 

C Task-build instructions* 
C 

C LINK/CHECKPOINT/MAP M ISC* LB* CI * 1 "IFOROTS/LIBRARY 

C since the task must be checkpointable to disable 

C checkpointing and to extend its size* 

C 

C Install and Run instructions* 
C 

C Install the task* Then Run it to start it up* 

C The task will suspend itself several different 

C times* Each time* use the command 

C SHOW TASKS ♦ MISC/ACTI YE/FULL (MCR ATL MISC) 

C to examine the changes* Use the command 

C CONTINUE MISC (MCR RESUME MISC) 

C to resume the task* 

C- 

INTEGER DSW*DRCTU 
O CALL SUSPND(DSW) ! Suspend to allow check 

C ! of status 

IF (DSW*LT*0) GOTO 1010 ! Branch on directive 
C .'error 
C Make some changes and then suspend again 

CALL DISCK'P(DSW) ! Disable checkpointing 

IF (DSW*LT*0) GOTO 1020 

CALL ALTPRI < » 10*DSW) ! Alter running priority 

IF (DSW*LT*0) GOTO 1030 
O CALL SUSPND(DSW) ! Suspend to allow check 

C ! of status 

IF (DSW*LT*0) GOTO 1040 
C Make some other changes and then suspend again 

CALL ENACKP(DSW) ! Reenable checkpointing 

IF (DSW*LT*0) GOTO 1050 

CALL ALTPRI < * *DSW) ! Return priority to 

C .'original 
IF (DSW*LT*0> GOTO 1060 

CALL EXTTSK ( "200*DSW) ! Extend task size by 
C ! 200(8) blocks 

IF (DSW*LT*0) GOTO 1070 
O CALL SUSPND(DSW) .' Suspend again 

IF (BSW*LT*0) GOTO 1080 

CALL EXIT ! Exit 

C Error handling 
1010 WRITE (5*1015) DSW 

1015 FORMAT (' ERROR ON 1ST SUSPEND* DSW = '*I5) 

GOTO 1100 
1020 WRITE (5*1025) DSW 



Example 2-2 Using Some Miscellaneous Directives (Sheet 1 of 2) 
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:l.025 FORMAT (' ERROR ON DISABLE CHECKPOINTING * DSW ~ 

1 9 15) 

GOTO 1100 
1030 WRITE (5*1035) DSW 

1035 FORMAT (' ERROR ON 1ST ALTER PRIORI TY * DSW = '* 
115) 

GOTO 1100 
1040 WRITE (5* 1045) DSW 

1045 FORMAT ( ' ERROR ON 2ND SUSPEND ♦ DSW '*I5) 

GOTO 1100 
1050 WRITE (5*1055) DSW 

1055 FORMAT (' ERROR ON ENABLE CHECKPOINTING * DSW = ■ 

1*15) 

GOTO 1100 
1060 WRITE (5*1065) DSW 

1065 FORMAT (' ERROR ON 2ND ALTER PRIORITY* DSW = '* 
115) 

GOTO 1100 
1 070 WR I TE (5*1 075 ) DSW 

1075 FORMAT (' ERROR ON EXTEND TASK, DSW « '15) 

GOTO 1100 
1080 WRITE (5*1085) DSW 

1085 FORMAT (' ERROR ON 3RD SUSPEND ♦ DSW ~ '*I5) 
1100 CALL EXIT 
END 



Run Session 



>INS MISC 
.'•RUN MISC 

>SHOW TASKS/ACTIVE FULL MISC 

070310 01123600-01170100 PRI - 50 ♦ DPR I - 50* 

•PMD 

TI - TTli: IOC -- 0, BIO -•• 0* EFLG - 000000 000000 PS -- 170000 

©PC -- 001640 REGS 0~6 000001 001242 001242 000000 001432 003572 001242 
^CONTINUE MISC 

>SHOW TASKS/ACTIVE FULL MISC 



OfMISC 067250 GEN 
[ STATUS ♦ SPN -Pi 



[ 



01 MISC 067250 GEN 070310 01123600-01170100 PRI - 10. DPRI - 50* 



STATUS J CKD SPN -PMD 

TI - TTli: IOC -- 0* BIO -- 0, EFLG - 000000 000000 PS - 170000 
PC -- 001640 REGS 0~6 003626 001242 001242 000000 001432 003572 001242 
s-CONTINUE MISC 

>SHOW TASKS/ ACTIVE FULL MISC 

070310 01123600-01210100 PRI - 50* DPRI - 50* 

PMD 

TI - TTli: IOC - 0* BIO - 0* EFLG -- 000000 000000 PS - 170000 
PC - 001640 REGS 0-6 003626 001242 001242 000000 001432 003572 001242 
^•CONTINUE MISC 

>SHOW TASKS/ACTIVE FULL MISC 
ATI.. — Task not active 



.'•SI-IUW I HSI\»/Ht I iVt 

OTmISC 067250 GEN 
\_ STATUS* SPN -Pf 



Example 2-2 Using Some Miscellaneous Directives (Sheet 2 of 2) 
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Run Time Conversion Routines 

As mentioned earlier, the system maintains task names, partition 
names, and certain other data in Radix-50 format in order to save 
space. There are times when conversions between ASCII and 
Radix-50 format need to be performed at run time. For example, 
you can modify Example 2-1 (REQUES. FTN) , so an operator can type 
in the task name at run time. This ASCII name would have to be 
converted at run time to Radix-50 format. The function RAD50 or 
the subroutine IRAD50 is used to perform the conversion. The code 
segment shown below illustrates the use of the function RAD 5 : 

DIMENSION TAS KNM ( 2 ) 
READ (5,1) TASKNM 
1 FORMAT (2A4) 

CALL REQUES (RAD50 (TASKNM) , , IDSW) 

If the Get Task directive (CALL GETTSK) is used to retrieve task 
information, the task name and partition name are returned in 
Radix-50 format. If you wish to display these, you need to 
convert them to ASCII format. The subroutine R50ASC is provided 
for this purpose. The program shown below illustrates the use of 
the R50ASC subroutine: 

DIMENSION IBUFF(16) 

CALL GETTSK (IBUFF) 

CALL R50ASC (6, IBUFF ( 1) , TASKNM) 

CALL R50ASC ( 6 , IBUFF ( 3) , PARTNM) 

WRITE (5,1) TASKNM 

WRITE (5, 2) PARTNM 

1 FORMAT (' TASK NAME IS 1 ,A6) 

2 FORMAT (' PARTITION NAME IS ' ,A6) 
END 
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NOTIFYING A TASK WHEN AN EVENT OCCURS 

Often a task needs to know when an event has occurred. The event 
may have occurred within another task; for example, when the task 
has completed a requested function. The event may instead have 
occurred within the system; for example, when a requested I/O 
operation is completed. There are two methods for implementing 
synchronization, event flags and asynchronous system traps. 



Event Flags 

There are three types of event flags: local, global 
and group global. Ninety-six event flags are made 
tasks, each with a unique number ( 1 ( 10) -96 ( 10) ) . 

Local event flags are provided for each task. There are 32(10) 
local event flags, numbered 1 ( 10) -32 ( 10) . These flags are used to 
synchronize a task with an Executive service, such as an I/O 
transfer. One task cannot reference another task's local event 
flags, so they cannot be used to synchronize tasks with one 
another. Local event flags 25 (10) -32 (10) are reserved for system 
use and hence should not be used by a user task. 

Global or Common event flags are provided for synchronization 
among different tasks. There is one set of 32(10) global event 
flags for the system numbered 33 (10) -64 (10) . These flags can be 
referenced by any task. Global event flags 57 (10) -64 (10) are 
reserved for system use and should not be used by user tasks. 

NOTE 

There is no way to protect against other 
tasks using global event flags. Great care 
must be taken to ensure that global event 
flags aren't used at the same time by several 
different users. Check with your system 
manager before using any global event flag to 
insure that it is not used for some other 
purpose . 



(or common) , 
available to 
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There are only 32(10) global event flags available system-wide. 
If additional event flags are needed, another set of event flags 
can be created for synchronization among different tasks. 32(10) 
group global event flags, numbered 65 (10) -96 (10) , can be created 
for any UIC group number. These event flags can be referenced by 
any task running under the correct group number. Hence, they can 
be used to synchronize tasks running under that group number, and 
offer an additional advantage in that they cannot be referenced by 
tasks running under other group numbers. 

Group global event flags are created using the DCL SET GROUPFLAGS 
CREATE (FLA /CRE in MCR) command or the Create Group Global Event 
Flags (CRGF$) directive. When users in a group don't need them 
anymore, the group global event flags can be marked for deletion 
using the DCL SET GROUPFLAGS DELETE (FLA /ELIM in MCR) command or 
the Eliminate Group Global Event Flags (ELGF$) directive. After 
that, when all active tasks in the group have finished using them, 
the group global event flags are eliminated. 



Using Event Flags for Synchronization 

LEARNING ACTIVITY 2-1 

Read section 2.2 (on Event Flags) in the 
RSX-11M/M-PLUS Executive Reference Manual . 
Pay particular attention to the examples . 
This section covers how event flags can be 
used for synchronizing tasks. When you have 
finished reading the material, answer the 
following questions. The answers are 
provided in Appendix G. 

Questions: 

1. In Example 1 in the reading, how can Task 
B do some work while waiting for event 
flag 35 to be set by Task A? 

2. What would happen in Example 2 if a local 
event flag (e.g., 1) were used instead of 
a common event flag? 

3. Why is a local flag satisfactory in 
Examples 3 and 4? 
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Examples of the Use of Event Flags for Synchronization 

Examples 2-3 and 2-4 show the use of event flags to synchronize 
two tasks. WFLAG creates the group global event flags for the 
group. It then clears event flag 65(10) and waits for that flag 
to be set. SFLAG sets event flag 65(10), which unblocks WFLAG. 
Run WFLAG first, then run SFLAG. 

The following notes are keyed to the examples. Note 5 is in 
SFLAG; all others are in WFLAG. 

Q Create the group global event flags. The default group 
number (used here) is the group number that the task is 
running under. 

Q An error is reported if the flags already exist. This 
isn't a fatal error, so we check for this condition. If 
the flags do exist, print a message and continue. 

O The flag is in an unknown state at startup. Therefore, we 
must clear the flag before waiting for it to be set. 

O Wait for the event flag to be set by SFLAG. This causes 
WFLAG to be blocked. Now run SFLAG. 

Set event flag 65 in task SFLAG. This allows WFLAG to 
become unblocked. SFLAG then exits. 

Q When WFLAG is unblocked and it continues executing, it 
starts up here. We check for any directive error entering 
the Wait For state, print a message, and exit. 

In certain programming situations it may be necessary to test one 
or more event flags to see if they are currently clear or set. 
The CALL READEF directive can be used to read a single flag. 
After the flag has been read, the contents of the DSW will 
determine the condition of the flag . If DSW=2, the flag was set; 
if DSW=0, the flag was clear. 
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C 
C 
C 
C 
C 
C 
C 
C 

c 
c 
c 
c 
c 
c 

10 



PROGRAM WFLAG 
FILE WFLAG *FTN 



This task creates the Sroup global event flags? and 
then clears event flag 65* and waits for it to be set* 
When the flag is sety it writes a message and exits 



Install and run instructions J 

Run WFLAG y then run SFLAG* At least one of the 
tasks must be installed? or else the RUN command 
will try to install both tasks under the same 
name (TTnn) 

WRITE <5vl0> 

FORMAT (' WFLAG IS CREATING THE GROUP GLOBAL EVENT 
1 FLAGS') 
©CALL CRGF (yIDSW) 

0IF (IDSW *LT* 0) GOTO 900 
15 WRITE (5*20) 

20 FORMAT (' CLEAR AND THEN WAIT FOR EF 65* TO BE SET') 

CALL CLREF (65? IDSW) 

IF (IDSW ♦LT. 0) GOTO 1100 
£) CALL WAITFR (65? IDSW) 
IF (IDSW .LT* 0) GOTO 
WRITE (5y30) 
FORMAT (' EF 65* 
LCALL EXIT 
C Error processing 
C 

C Check for code of -17 y 
"900 IF (IDSW ♦ NE ♦ -17) GOTO 1000 

C In that case* Just dislay a message and continue* 
WRITE (5y910) 

FORMAT (' GROUP GLOBAL EVENT FLAGS ALREADY EXIST') 
GOTO 15 

for fatal errorsy display message and 
WRITE (5y 1010) IDSW 
FORMAT (' DIRECTIVE 
1 EF ' 'S* DSW = ' yI5) 
CALL EXIT 

WRITE (5yl.U0) IDSW 

FORMAT (' DIRECTIVE ERROR CLEARING EVENT FLAG 65* 
.1 DSW * 'yI5) 
CALL EXIT 



30 



1200 



HAS BEEN SET* WFLAG WILL NOW EXIT') 



meaning flags already exist 



9.10 

C Here 

1000 

1010 



1100 
.1.110 



>>;i t 



ERROR CREATING GROUP GLOBAL 



Example 2-3 Waiting for an Event Flag (Sheet 1 of 2) 
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3.200 WRITE (5»1210) IDSW 

1210 FORMAT (' DIRECTIVE ERROR WAITING FOR EVENT FLAG 
1 65* DSW - '»I5> 
CALL EXIT 
END 



Run Session 

>INS WFLAG 
>INS SFLAG 
>RUN WFLAG 

WFLAG IS CREATING THE GROUP GLOBAL EVENT FLAGS 
CLEAR AND THEN WAIT FOR EF 65* TO BE SET 
RUN SFLAG 

EF 65* IS BEING SET* THEN SFLAG WILL EXIT ♦ 
EF 65 ♦ HAS BEEN SET* WFLAG WILL NOW EXIT 



Example 2-3 Waiting for an Event Flag (Sheet 2 of 2) 
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PROGRAM SFLAG 

C 

C FILE SFLAG *FTN 
C 

C This task sets event flag 65* It assumes that the 
C group global event flags have already been created* 
C 

C Install and run instructions* 
C 

C Run WFLAGy then run SFLAG* At least one of the 

C tasks must be installed? or else the RUN command 

C will try to install both tasks under the same 

C name ( TTnn > ♦ 

c: 

WRITE (5*10) 

10 A FORMAT (' EF 65* IS BEING SET ♦ THEN SFLAG WILL EXIT') 

Q CALL SETEF <65>IDSW> 
C The DSW value returned for SETEF is 2 if it was set 
C and if it was clear* A 1 is NOT returned for success 

IF (IDSW *LT* 0) GOTO 1000 

GALL EXIT 
C Error code 
1000 WRITE <5» 10.1.0) 

1010 FORMAT (' DIRECTIVE ERROR SETTING EF 65* DSW * ' 
If 14) 
CALL EXIT 
END 



Example 2-4 Setting an Event Flag 
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ASYNCHRONOUS SYSTEM TRAPS(ASTs) 

Asynchronous System Traps (ASTs) are used to detect events that 
occur asynchronously to a task's execution. We say that they 
occur asynchronously to a task's execution because they occur at 
unpredictable times, depending on conditions which the task cannot 
control. By doing some work and then periodically checking an 
event flag to check on an event, a task can do work while waiting 
for an event to occur. However, this means that the task must 
periodically stop its work to check the flag. 

Using an AST gives the Executive the responsibility for monitoring 
the event. The Executive will "interrupt" the task and transfer 
control to a special user written routine when the event has 
occurred. Using this technique is more efficient because the task 
doesn't have to do any periodic checking, and it probably results 
in faster notification because the task is notified right after 
the event occurs. With periodically reading the flag, it may take 
quite a while to notice that the event has occurred if it occurs 
immediately after a check. 

The only directives which allow the use of ASTs from FORTRAN are 
CNCT, PWRUP, SDRC, SDRP, SPAWN, SREA and SREX. 
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Figure 2-1 shows how an AST routine works. The following notes 
are keyed to the figure. 

Q The user specifies an AST routine in a directive. The 
Executive sets up for the AST. 

Q The Executive returns control to the user task. 

Q When the system determines that the event has occurred 
which corresponds to the specified AST routine, the 
Executive passes control to the AST routine, executing it 
before any other user code in the task. This means that if 
the task is executing at the time of the AST, the task is 
"interrupted" until the AST routine is executed. The AST 
routine is executed even if the task is stopped or blocked. 
In that case, the task returns to its stopped or blocked 
state after the AST routine is executed, unless the AST 
routine or some external event unstops or unblocks the task 
in the meantime. 

Q The AST routine is a user written routine contained within 
the task. 

The AST routine uses a standard RETURN statement to return 
control to the main code via the Executive. However, 
before the actual return, the Executive checks to see if 
any other ASTs have occurred while the AST routine was 
executing. Any such additional ASTs are queued in an AST 
pending queue in a first-in-first-out order; these ASTs 
are also serviced before the Executive returns to the point 
at which the AST interrupt occurred. 

For additional information on ASTs, see section 1.5.4 in 
Chapter 1 and sections 2.3.3 and 2.3.4 in Chapter 2 of the 
RSX-11M/M-PLUS Executive Reference Manual . 
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TASK CODE EXECUTIVE CODE 




TK-7508 



Figure 2-1 AST Sequence 
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Example 2-5 shows the use of ASTs. An AST routine is entered if 
an abort request is made by either another task or an operator. 

The following notes are keyed to the example. 

Q Set up for AST on abort attempt. 

Q Loop until abort request comes in. 

O Service routine entered on first abort request. For this 
particular AST, a nonpr ivileged task enters this routine 
only once and further ASTs are cancelled. If the task is 
built as a privileged task, the routine is entered each 
time an abort attempt comes in. See Appendix D for an 
explanation of privileged tasks. 

Q Note that FORTRAN I/O cannot be performed in an AST routine 
because the I/O code is not reentrant; therefore any I/O 
to be done in an AST routine must be done via QIO 
directives. The next module will discuss the QIO directive 
in detail. 

Another directive, SREX, gives extended capabilities. An entry 
passed to the AST routine indicates whether the abort request came 
from a privileged or nonpr ivileged task or user and further, 
whether it came from an Abort Task directive or a DCL (or MCR) 
command. Each case can be handled differently. 
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PROGRAM ASTEX 

Of 

C FILE ASTEX.FTN 
C 

C This task sets up a Specify Reauest Exit AST routine* 
C It then sits in a loop until someone tries to abort 
C it* At that pointy it enters the AST routine and sends 
C out a message* It won't abort the first time* A second 
C abort attempt will succeed because for this particular 
ASTy the first AST entry cancels any further AST's for 
C this event 
C 

C Compile instruct ions J 
C 

C The AST routine must be compiled with traceback 

C disabled* Since in this case the AST routine source 

C is in the same file as the ma in line? compile both with 

traceback disabled* 
C 

C For FORTRAN IV* 
C 

C FORTR AN/NOL I NE...NUMBERS/L 1ST ASTEX 

C 

C For FORTRAN IV-PLUS or FORTRAN-- 77 
C 

C F0RTRANIZ/F4P or /F773/N0TRACE/LIST ASTEX 

C 

C Run notes* Remember to use the name the task is 
installed under when attempting to abort the task* 
C-- 

INTEGER DSW 
EXTERNAL REXAST 

CALL SREA< REXAST y DSW) ! Set up Specify Exit AST 
IF <DSW*LT*0> GOTO 1001 ! Branch on error 
TYPE *y "ASTEX STARTING UP* WILL WORK UNTIL ABORTED* 
C Do some work* 
.10 DO 20 1= -32767 1 32767 

20 CONTINUE 
GO TO 10 
C Error code 

100.1 TYPE *y 'ERROR ON DIRECTIVE y DSW 'yDSW 
CALL EXIT 
END 



O 



Example 2-5 Using a Requested Exit AST (Sheet 1 of 
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SUBROUTINE REX AST 

C 

C AST service routine? 
O 

I NTEGER PL I ST < 3 ) y I OW VB 
REAL TEXT 1 < 6 > y TEXT 2 < 7 ) 
DATA IOUVB/" 11000/ 

DATA TEXT 1 / ' TRY I ' 9 ' NG T ' 9 ' AB ' 9 

l'ORT ' y ' ME ' 9 ' EH? V 

DATA TEXT 2 /"WE W ' 9 ' ON ' ' T ' 9 ' LET ' 9 

1 •' YOU ' y ' THI ' 9 'S TI ' » ' ME ! V 
C Set up for QIC) directive 

CALL GET ADR ( PL 1ST < 1 ) , TEXT1 ( 1 ) ) 

PL I ST (2) « 23 
■PLISTO) ~ "40 
C Use QIO directive to display text 

O CALL UlTQIOdOWVBySyl yyyPLIST) 
C Set up for 2nd line of text 

CALL GET ADR ( PL I ST < 1 ) y TEXT2 < 1 ) ) 

PLIST<2) « 27 
C Use QIO directive to display text 

CALL WTQIOdOWVBySylyyyPLIST) 

RETURN 

END 



Run Session 



>INS ASTEX 
>RUN ASTEX 

ASTEX STARTING UP* WILL. WORK UNTIL ABORTED* 
ABORT/TASK ASTEX 

TRYING TO ABORT MEy EH? 
WE WON'T LET YOU THIS TIME! 
ABORT/TASK ASTEX 

10:57:02 Task -ASTEX " terir.ir.3ted 

Aborted via directive or CLI 



Example 2-5 Using a Requested Exit AST (Sheet 2 of 2) 
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Now do the tests/exercises for this module in the tests/exercises 
book. They are all lab problems. Check your answers against the 
solutions provided, either in that book or in on-line files, under 
UFD [202,2], 

You will need the program READF.FTN to do question 1. It should be 
available on-line probably under UFD [202,1]. In case it is not 
available on-line, the source code is listed in Appendix G. 

If you think that you have mastered the material, ask your course 
administrator to record your progress in your Personal Progress 
Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, return to 
this module for further study. 
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USING THE QIO DIRECTIVE 



INTRODUCTION 

All Input/Output under RSX-11M is performed using QIO directives. 
In this module, you will learn how to use the QIO directive, 
concentrating on its use for input/output to a terminal. 



OBJECTIVES 

1. To use the QIO directive to perform I/O to a 
non-file-structured device 

2. To choose either synchronous or asynchronous I/O as the 
most effective method 

3. To perform complete error checking upon I/O completion 



RESOURCES 

1. RSX-11M/M-PLUS Executive Reference Manual , Chapter 5 for 
specific directives 

2. RSX-11M/M-PLUS I/O Driver's Reference Manual , Chapters 1 
and 2 
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OVERVIEW OF QIO DIRECTIVES 

All I/O operations under RSX-11M are performed using QIO 
directives. While transparent to the user, all FORTRAN READ and 
WRITE statements are ultimately transformed into QIO directives*. 
The QIO directive causes an I/O request to be passed to the 
appropriate service routine. The service routine is either a 
device driver or a system task called an ancillary control 
processor (ACP) . There is a device driver for each device type on 
the system. There are three ACP's provided, F11ACP for FILES-11 
structured disks, MTAACP for ANSII magtape, and NET ACP for DECNET. 

The I/O packet is placed in an I/O queue for the service routine. 
The packets are queued in the order of the priority of the issuing 
tasks. If there are multiple requests at a given priority, those 
requests are queued first-in-first-out (FIFO) . The QIO directive 
does not perform the I/O operation itself, but simply queues the 
request to the appropriate service routine, which performs the 
actual I/O transfer. After the I/O request has been queued, the 
Executive returns control to the issuing task, unless the task 
requests the Executive to place the task in a Wait For state until 
the I/O transfer completes. 



PERFORMING I/O 

QIO directives are generally used by a programmer for I/O on 
non-file-structured devices such as terminals. For file I/O, all 
READ and WRITE statments are passed off to the File Control 
Services (FCS) or Record Management Services (RMS) , which in turn 
issue the appropriate QIOs for you. When using QIOs, you specify 
which I/O operation (e.g., Read Virtual Block or Write Virtual 
Block) is to be performed by means of an I/O function code. 
Specify the device by means of the logical unit number (LUN) . You 
specify additional information about the I/O operation (e.g., what 
buffer to write and how many characters) by means of an I/O 
parameter list (IOPL) . All of this information is passed to the 
Executive through parameters in the Directive Parameter Block 
(DPB) , as it is with all directives. 
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USING QIO DIRECTIVES IN FORTRAN 

There are two basic reasons for using QIO directives in FORTRAN • 

• To acheive asynchronous I/O. 

All READ and WRITE statements are synchronous; i.e., the 
program is put into a Wait For state until the I/O is 
complete. If you need to perform asynchronous I/O, it can 
only be done via QIO directives. 

• To perform I/O functions not possible with READ and WRITE 
statements. 

Certain I/O functions, particularly to a terminal, cannot 
be done by READ and WRITE statements. Some examples are 
read with no echo and cursor control on a video terminal. 
By using QIO directives, these functions can be done from 
FORTRAN programs. 



I/O FUNCTIONS 

Each device type has its own set of legal I/O functions. Certain 
functions are called standard or common, since they are available 
on all devices. The seven standard I/O functions are listed in 
Table 3-1. Logical block transfers (Read Logical Block and Write 
Logical Block) can usually be performed for any device. For file 
structured devices, virtual block transfers can be performed only 
if a file is open on the device. 

If Virtual Block I/O is requested for a non-file-structured 
device, such as a terminal, it is converted to logical block I/O 
for you. In addition, devices may have additional device specific 
functions, such as Read No Echo at a terminal. Each function 
requires its own set of parameters, which are specified in an I/O 
parameter list. 
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Table 3-1 Common (Standard) I/O Functions 



Global Symbol 

4 r\ M&PDH 
1 n rLf\^ KU 


Octal 

Value 


r unction 


Suggested 

KTIDTO JVM Mama 

cUninnn in a hi e 


TO ATT 


01011 A0101 

YJ Xl X 1 V V 




TOATT 

X \Jt\ X X 


TO f)PT 


Of 01 9 01 01 01 


T*>of fl^h rlpui pp 

L/C UuUU UCV l^C 


TDDFT 

X UUD X 


IO.KIL 


000012 


Cancel I/O requests 


IOKIL 


IO.RLB 


001000 


Read Logical Block 


IORLB 


IO.RVB 


010400 


Read Virtual Block 


IORVB 


IO.WLB 


000400 


Write Logical Block 


IOWLB 


IO.WVB 


011000 


Write Virtual Block 


IOWVB 



Throughout the literature you will find I/O function codes given 
in the form used by MACRO programmers; for example, 10. ATT and 
IO.DET. In MACRO, these codes can be used directly as function 
codes in a QIO directive, and the proper octal values will be 
inserted. In FORTRAN, you must determine the octal value for the 
function and use that value in the CALL QIO or CALL WTQIO. For 
instance, to issue an ATTACH, you could use: 

CALL QIO("1400, , , , , , ,) 

In order to make QIO calls more readable, it is recommended that 
you create a DATA statement for any needed QIO functions using the 
suggested variable names shown above. While the actual name is 
arbitrary, (but must be an integer variable) , a certain degree of 
standardization will be achieved by using the MACRO symbol without 
the period (IOATT versus 10. ATT) . Hence to perform an ATTACH: 

DATA IOATT/" 1400/ 
CALL QIO (IOATT, ,,,,,,) 

The octal values for all function codes can be found in Appendix B 
of the RSX-11M/M-PLUS I/O Driver's Reference Manual. 
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LOGICAL UNIT NUMBERS (LUNs) 

The device for an I/O operation is specified by means of a logical 
unit number. The correspondence between logical unit numbers and 
physical devices is made initially at task-build time. 

The default LUN assignments set up by the Task Builder are as 
follows: 



LUN 


#1 


- SY: 


LUN 


#2 


- SY: 


LUN 


#3 


- SY: 


LUN 


#4 


- SY: 


LUN 


#5 


- TI: 


LUN 


#6 


- CL: 


LUN 


#7 


- TI: 



LUN 7 is typically used for error messages. 

These default assignments may be overridden at task-build time by 
using the ASG option. Additional LUNs can be created (up to a 
total of 250 LUNs) by using the UNITS option. 

Once a task is installed, an operator can check the LUN 
assignments for the task by using the DCL SHOW LOGICAL__UNITS 
command (LUN in MCR) . The assignments can be changed by an 
operator using the DCL ASSIGN/TASK command (REA in MCR). The LUN 
assignments can also be checked at run time using the Get LUN 
directive (CALL GETLUN) , and changed using the Assign LUN 
directive (CALL ASNLUN) . 

SYNCHRONOUS AND ASYNCHRONOUS I/O 

There are two kinds of I/O, synchronous I/O and asynchronous I/O. 
With synchronous I/O, the Executive provides sychronization , When 
a task issues an I/O request, it doesn't get control back from the 
Executive until after the I/O packet is queued, and the I/O 
operation (the transfer performed by the service routine itself) 
is completed. In other words, the synchronous I/O request asks 
the Executive to queue the I/O packet and then place the task in a 
"Wait For" state, waiting for the specified event flag to be set, 
at which time the actual I/O is complete. 
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Figure 3-1 shows the flow of instructions during the processing of 
a synchronous I/O operation. The task does not execute the 
instruction following the QIO directive until after the I/O 
transfer itself has completed. 

Figure 3-2 shows a time diagram illustrating the same I/O 
operation. Note that once the QIO directive is executed at st:ep 
1, the task doesn't execute again until step 8, after the transfer 
has completed. The system handles all synchronization with 
synchronous I/O. Use the CALL WTQIO directive to invoke this type 
of I/O. (CALL WTQIO is a combination of a QIO and a WAITFR) . 



Commentary to Figures 3-1 and 3-2: 

Q User task executes WTQIO directive. 

Q Executive queues the I/O request. 

Q Executive calls the driver. 

Driver begins the I/O transfer. 

Q Driver handles I/O transfer as necessary. 

O I/O transfer completes. 

Q Driver finishes up and notifies task the I/O is completed. 

Q User task continues. 
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EXECUTIVE 



USER TASK 



IQIO DIRECTIVE 
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Figure 3-1 Execution of a Synchronous I/O Request 
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Figure 3-2 Events in Synchronous I/O 
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With asynchronous I/O, the Executive still queues the I/O request. 
However, when a task issues an asynchronous I/O request, the 
Executive passes control back to the task immediately after the 
I/O packet is queued to the driver. You must provide 
synchronization concerning the completion of the actual I/O 
transfer. This could occur at various times, depending upon such 
factors as how many other I/O packets are already in the driver's 
I/O queue, and the speed of the device itself. The task executes 
in parallel while the I/O transfer takes place. In Figure 3-3, 
the instruction after the QIO request is executed after the I/O 
packet is queued and the driver has started the transfer, not 
after the I/O transfer completes. The task continues executing 
unless it chooses to wait. Figure 3-4 shows a time diagram 
illustrating asynchronous I/O. 

Note that after the QIO directive is executed at 1 , the task 
begins executing again at step 5 . In this example, the task 
waits for the I/O transfer to complete at step 5a . If you use 
asynchronous I/O, you must provide any synchronization yourself, 
using event flags or by testing the I/O status block. The task 
shown in Figures 3-3 and 3-4 uses a Wait For Event Flag directive 
at step 5a . Use the directive CALL QIO to invoke this type of 
I/O. 

The advantage of asynchronous I/O is that your task can continue 
processing in parallel with the I/O transfer. For example, you 
can perform computations while waiting for a read or a write 
operation to complete. Of course, if you need the information 
from the read before you can do anything else, it is better to use 
synchronous I/O. 
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Commentary to Figures 3-3 and 3-4: 

User task executes QIO directive. 
Q Executive queues I/O request. 
Q Executive calls the driver. 

Q Driver begins the I/O transfer, and passes control back to 
the user task. 

Q Driver handles I/O transfer as necessary. User task 
executes in parallel with I/O transfer. 

Q User task waits for I/O operation to complete. 

O I/O transfer completes. 

Q Driver finishes up and Executive notifies task that I/O is 
completed . 

O User task continues. 
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Figure 3-3 Execution of an Asynchronous I/O Request 
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Figure 3-4 Events in Asynchronous I/O 



USING THE QIO DIRECTIVE 



MAKING THE I/O REQUEST 

Specify the following information in the CALL QIO or CALL WTQIO 
when requesting I/O: 

• Synchronous or asynchronous I/O, by using the appropriate 
directive. 

• The I/O function to be performed. 

• The LUN to be used for the I/O operation. 

• An event flag number, if any, to be used for 
synchronization. This is required for synchronous I/O. 

• The address of an I/O Status Block (IOSB) . The IOSB is 
used to pass status and other information about the I/O 
operation back to the task. 

• The I/O parameter list (up to six words) which specifies 
information for the particular device and I/O function 
requested. 

• The Directive Status Word (DSW) 

Table 3-2 shows the I/O parameter list arguments which are needed 
for each of the standard I/O functions with the full-duplex 
terminal driver. Note that for write logical block and write 
virtual block, the vertical format control characters are the 
standard FORTRAN carriage control characters. 

Table 2-3 in section 2.3 of the RSX=11M/M-PLUS I/O Driver's 
Reference Manual lists these standard functions and the other 
device-specific functions available with the full-duplex terminal 
driver. The device-specific functions will be discussed later in 
this module. If your RSX-11M system has the half-duplex terminal 
driver, Table 3-3 in section 3.3 lists the functions available 
with that driver. For other devices, there is a corresponding 
table in the appropriate chapter of the manual. 
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Table 3-2 I/O Parameter List for Standard I/O Functions 



Function I/O Parameter List 



Attach 




None needed 


Detach 




None needed 


Kill 




None needed 


Read Virtual 


Block 


word 1 - 


buffer starting address 


and 




word 2 - 


buffer size (in bytes) 


Read Logical 


Block 


word 3 - 


optional timeout count 








(in 10 second intervals) 






NOTE: 


Only used if a special sub- 








function bit is set. See the 








section on Terminal I/O. 






words 4, 


5 r and 6 — unused 


Write Virtual 


Block 


word J. 


UUEIci buai Lilly aQUI cob 


and 




wo rd 2 - 


buffer size (in bytes) 


Write Logical 


Block 


word 3 - 


vertical format control, as 








follows (these are the standard 








FORTRAN carriage control char- 








C *a K Q \ • 






Octal 


ASCII 






value 


character Meaning 






040 


blank single space 






060 


double space 






061 


1 form feed 






044 


$ prompting output- 








stay in same 








location after 








output 






053 


+ overprint 






000 


null no implied format 








control - use 








internal control 






words 4, 


5, and 6 - unused 
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THE I/O PARAMETER LIST IN FORTRAN 

The parameter list must refer to an integer array declared in a 
DIMENSION statement with a dimension of six. When used in a QIO 
directive, the parameter list array name is used without a 
subscript. 

DIMENSION IPAR(6) 
CALL QIO(, , , , , IPAR,) 

Some entries in the parameter list must be the addresses of arrays 
or variables. Since FORTRAN does not provide this capability, you 
must use a system subroutine called GETADR to get the addresses. 
(See the RSX-11M/M PLUS Executive Reference Manual and the 
appropriate user's guide for further information. To get the 
addresses of two variables IBUFF and JBUFF and place the addresses 
in array K, use the following: 

DIMENSION K(2) 

CALL GETADR (K, IBUFF, JBUFF) 

The address of IBUFF will be in K(l) and the address of JBUFF will 
be in K(2) at the completion of the CALL GETADR. 



ERROR CHECKING AND THE I/O STATUS BLOCK 

There are two kinds of errors which can be produced by QIO 
directives, directive errors and I/O errors. The various 
directive and I/O status codes and their meanings are listed in 
Appendix B of the RSX-11M/M-PLUS I/O Drivers Reference Manual and 
also in the RSX-11M Mini-Reference . 

Directive errors are produced due to errors in processing the 
directive and getting the I/O packet queued up to the device 
driver. As with other directives, QIO directive errors are 
indicated by a negative value in the DSW upon return to the task 
code. Success is indicated by a positive value (typically +1) in 
the DSW. Thus, the directive status indicates the success or 
failure of the attempt to queue the I/O packet. Check for 
directive errors immediately upon return to the task, after the 
QIO directive is issued. 



76 



USING THE QIO DIRECTIVE 



Upon completion of the I/O transfer itself, the Executive returns 
status information concerning the I/O transfer to the I/O Status 
Block laid out as follows: 



Device 


Dependent 


I/O Status 


Actual 


Number of Bytes 


Transferred 



word 
word 



The low-order byte of the first word of the I/O Status Block 
contains the I/O status code. Note that this is a byte value, not 
a word value. A positive I/O status code (usually +1) indicates 
success. Negative values indicate various error conditions. The 
second word of the I/O status block indicates the number of bytes 
actually transferred, which is significant in the case of any read 
or of a write which ends after only some of the data is 
transferred. The device dependent byte indicates, for reads, the 
character which was used as a terminating character (<RET>, 
CTRL/Z, <ESC>, etc.) . 

The I/O status byte should be checked only after the I/O transfer 
completes. For synchronous I/O, the I/O status should be checked 
immediately after checking the DSW, since the I/O transfer itself 
also completes before control is returned to you. For 
asynchronous I/O, on the other hand, the I/O status should be 
checked when the task is notified by the Executive that the 
transfer is complete. Synchronization is discussed in the 
following section, after an example of synchronous I/O. 



THE QIO DIRECTIVES 
Synchronous I/O 

The format of the CALL WTQIO is: 

CALL WTQIO ( if n , lun ,ef n ,pr i , iosb , iopl , ids) 



where 

ifn - I/O function code 
lun - Logical unit number 

efn - Event flag number (required for synchronous I/O) 
pri - Priority (not used but must be present) 
iosb - I/O status block address 

iopl - I/O parameter list, integer array up to six elements 
ids - Directive status word 
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An event flag must be specified for synchronous I/O. If one is 
not specified, the I/O request is handled as an asynchronous I/O 
request. The priority is included to allow compatibility with 
RSX-11D. It is not used in RSX-11M. The I/O parameter list is a 
single directive parameter. Hence, the entry must be for an array 
of up to six elements. Six words are always placed in the DPB for 
the I/O parameter list, whether or not all six words are 
specified. It is best to reserve six words. If you do not, you 
may end up with data from the array (s) defined immediately after 
the variable defined for the parameter being used in the parameter 
list for a QIO. 

Example 3-1 shows the use of synchronous QIOs. The following 
notes are keyed to the example. 

O The two-word (four-byte) I/O status block for return of 
I/O status and the buffer into which the data will be read 
and from which the data will be displayed. IOSB is 
declared as a byte array so that the program can examine 
the I/O status byte in I0SB(1). The program also needs to 
use the byte count of the number of bytes read by the QIO. 
This count is found in IOSB (3) and IOSB (4). Since the 
program needs this as an integer value, the 
EQUIVALENCE (NUM, IOSB (3) ) is used. 

IBUF is the buffer used to hold the characters read by the 
WTQIO directive. 

Q Issue the read request. We are using LUN 5, event flag 1, 
and IOSB which is the four-byte (two-word) array to 
receive I/O status after the IORVB. The I/O parameter 
list is set up as a single parameter (IPAR) which refers 
to an integer array. IPAR(l) must contain the address of 
IBUFF which is the buffer into which the characters will 
be read by the IORVB. Since this is an address, use CALL 
GETADR to get the address into IPAR(l). IPAR(2) is the 
maximum buffer size for the IORVB. If input is terminated 
with a terminating character, such as a carriage return, 
before 80 characters are typed, the number of characters 
actually read will be returned in the second word of the 
status block (I0SB(3)). Input will be terminated 
automatically after the eightieth character, if 80 
characters are typed. In that case, 80 will be returned 
in the second word of the status block. 

Q Check for directive error - failure to queue the I/O 
packet. 
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Q With synchronous I/O, the I/O operation has completed when 
we get control, so also check the I/O status. A value 
less than indicates an error in the I/O transfer. 

O The count of characters typed in is in NUM (I0SB(3)). 
Check on and convert only this many characters. Check 
each character to see if it is in the range ASCII A to 
ASCII Z. If so, convert to lowercase by adding 
32(10)=40(8) to that value, or else continue. 

O Write the buffer BUFF, which has the converted message. 
This is a Write Virtual Block. The third argument in the 
I/O parameter list, "40, is for vertical format control. 
"40, which is an ASCII space, indicates single line feed 
before writing the line. 

Q Check for directive error or I/O error. 

NOTE 

Although both virtual block and logical block 
operations are permitted to a terminal, it is 
safer to use virtual block operations. If 
the I/O is actually performed at a terminal, 
the virtual block request gets converted to a 
logical block request. If logical block 
writes are used and someone reassigns the LUN 
to a disk, for example, the write may 
overwrite a block on the disk. If, on the 
other hand, someone reassigns the LUN and 
write virtual blocks are used to a disk, the 
write will only be allowed if a file is open 
on the disk, which will fail in most cases if 
the program is writing to a terminal. 
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PROGRAM SYNC HQ 



C FILE SYNC HQ * FIN 

c; 

C 
C 
C 

c 
c 



This program reads a line of text from the terminal? 
converts any upper case characters to lower case and 
prints the converted message back at the terminal ♦ 
It uses synchronous QIO directives* 



A BYTE I0SB<4)»IBUF<80> 

DIMENSION I PARC 6) 
EQUIVALENCE ( NUM ? IOSB < 3 ) ) 
DATA IOWVB/'llOOO/ 
DATA I0RVB/"10400/ 
DATA IVFC/MO/ 
C Set up values for the QIO 
I UNITES 
IPAR<2>=80 
IPAR(3)=IVFC 
C Get the address of the I/O buffer 

CALL GET ADR < I PAR ( 1 ) y I BUF < 1 > > 
C Issue the QIO 

CALL WTQI0(I0RVB»IUNIT»1»>I0SB>IPAR>IDS> 
C Check the directive and I/O statuses 
ft. IF ( IDS A..T. 0) GO TO 800 
w 0IF (lOSBCI.) *LT* 0) GO TO 83.0 
C Check for uppercase characters and convert them to lowercase 
DO 100 :i>.unum 

IF <IBUF(I) .LT* 'A') GO TO 100 

IF ( IBUF ( I ) ♦ GT ♦ 90 ) GO TO 1 00 ! Z is 90 < 1 ) 

IBUF(I)*IBUF<I)+32 
.00 ""CONTINUE 

C Place the number of characters to write in the I/O parameter list 

IPAR(2)=NUM 
C Write the converted line to the terminal 

CALL WTQIOC IOWVBv lUNITs- .1. ? ? lOSBy IPAR? IDS) 
directive and I/O status 



C Check 



BOO 



{3.1.0 



820 



IF ( IDS *LT» 0) GO TO 820 
IF (IOSB(l) J...T* 0) GO TO 

GO TO 850 
WRITE (5» 900) IDS 
GO TO 850 

WRITE <5y 91 O)IOSB(l) 
GO TO 850 
WRITE(5»920)IDS 
GO TO 850 



830 



Example 3-1 Synchronous I/O (Sheet 1 of 2) 
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330 WRITE<5*930)I0SB< 1 ) 

850 CALL EXIT 

900 FORMAT << DIRECTIVE ERROR ON READ* CODE = '>I4> 

910 FORMAT (' I/O ERROR ON READ* CODE = ',I4> 

9120 FORMAT ( ' DIRECTIVE ERROR ON WRITE y CODE = '»I4> 

930 FORMAT < ' I/O ERROR ON WRITE t CODE « '»I4> 
END 



Run Session 



>RUN SYNCHQ 

ABCDEFGHIJklmnop«rstuvwxyzl2345678C3\ 
abode f Shi Jk 1 mnopc* rstuvwxyzl 2345678 C 3\ 



Example 3-1 Synchronous I/O (Sheet 2 of 2) 
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Asynchronous I/O 

The format of the CALL QIO is: 

CALL QIO(ifn,lun f efn,pri , iosb,iopl , idsw) 

where 

ifn - I/O Function code 
lun - Logical Unit Number 
efn - Event Flag Number 

pri - Priority (not used but must be present) 
iosb - I/O Status Block Address 
iopl - I/O Parameter List (up to 6 words) 
idsw - Directive status word 



Synchronization With Asynchronous I/O — As mentioned earlier, 
event flags may be used for synchronization. If an event flag is 
specified, the Executive clears the event flag when the I/O packet 
is queued and sets the flag again when the I/O transfer completes. 
This happens with both synchronous and asynchronous I/O, if an 
event flag is specified. With asynchronous I/O, the task can 
specify a flag and use it for synchronization using one of the 
following techniques: 

1. Do some work, then wait for the flag to be set. 

2. Work the entire time, periodically checking the flag until 
it is set. 

A third technique is to monitor the contents of the I/O status 
byte of the I/O status block. The entire I/O status block is 
cleared when the I/O request is queued to the driver. Later, it 
is filled in when the I/O transfer completes. Therefore, the user 
task can periodically check the contents of the I/O status byte 
for a nonzero value. 
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Example 3-2 demonstrates the use of asynchronous I/O to perform 
the same function performed in Example 3-1. This task can do some 
work in parallel with the I/O transfer. The following notes are 
keyed to the example. 

O Issue the read via CALL QIO instead of CALL WTQIO. All 
arguments are the same as for a CALL QIO. The Executive 
will clear event flag 1 when the I/O packet is Queued and 
set it when the I/O operation completes. 

O Check for directive errors immediately. Here, we are 
checking for an error in queueing the I/O packet. 

O While the I/O transfer itself takes place, we can do some 
work. Here we fill the array at K with the values 64, 
128, ...,640. 

O When we are finished with our work, we wait for the event 
flag specified in the CALL QIO directive. It will be set 
when the I/O operation completes. 

O Now that the I/O operation is finished, check for I/O 
errors. 

O After converting the message to lowercase, issue the 
write . 

O This time, we wait for the flag to be set right after we 
check the directive status. We could do some more work 
here. If in fact we are going to just wait, it is simpler 
and more efficient to use synchronous I/O (WTQIO) . 
Synchronous I/O is more efficient because we perform both 
functions (QIO and WAIT) in one Executive directive call. 

If you use an asynchronous QIO for either reading or writing, you 
should not use a FORTRAN READ or WRITE to the same lun until you 
are certain that the QIO has completed. 
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PROGRAM ASYNCQ 

C 

C FILE! ASYNCQ ♦ FIN 
C 

C This program reads a line of text from the terminal)' 
C converts any upper case characters to lower case and 
C prints the converted message back at the terminal* 
C It uses asynchronous QIOs and an event flag for 
C s y n c h r o n i z a t i o n ♦ 

c 

BYTE I0SB(4) yIBUF(80) 

D I MENS I ON I PAR ( 6 ) y K ( 1 ) 

EQUIVALENCE ( NUM v IOSB ( 3 ) ) 

DATA lOWVB/'HOOO/ 

DATA I OR VB/" 10400/ 

DATA IvFC/MO/ 
C Set up values for the QIO 

I UN I T-- 5 

IPAR (2) =80 

IPAR(3)=IvTC 
C Get the address of the I/O buffer 

CALL GET ADR < IPAR < 1 ) y IBUF ( 1 ) ) 
C Issue the QIO 

CALL Q 1 ( I OR VB y I UN I T y 5 y y I QSB y I P AR y I DS ) 
C Check the directive status 

IF (IDS *LT* 0) GO TO 800 
Do some work while I/O operation is being performed 

©DO 50 1=1 y 10 
K( I )~64*I 

50 CONTINUE 

C Wait for I/O to complete 

CALL WAITFR(5f IDS) 
C Check directive status 

IF (IDS ,LT. 0) GO TO 805 
C Check the I/O status 

IF (I0SB(1) *LT* 0) GO TO 810 
C Convert to lowercase 
DO 100 1=1 y NUM 

IF (IBUF(I) ♦ LT ♦ 'A') GO TO 100 
IF (IBUF(l') *GT* "132) GO TO 100 
IBUF(I)=IBUF(I)+32 
.1.00 CONTINUE 

C Bet up I/O Parameter List for write 

IPAR(2)=NUM 
C Write the converted line to the terminal 

CALL QIOaOWVBylUNITySy y IOSB y IPAR y IDS ) 
C Check directive status 

IF (IDS ♦LT* 0) GO TO 820 



Example 3-2 Asynchronous I/O Using Event Flags 
for Synchronization (Sheet 1 of 2) 
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wait f 

o 

Cheek 
Check 



C 



BOO 
BOS 
810 

B20 

B25 

830 
850 
900 
905 
910 
920 
925 
930 



or the I/O to complete 

CALL WAITER (5* IDS) 

d i r e c t i v e s t a t u s 

IF (IDS ♦ LT ♦ 0) GO TO 825 

the I/O status 

IF (I03B(1> ♦ LT* 0) GO TO 830 

GO TO 850 

WRITE (5* 900) IDS 

GO TO 850 

WRITE (5v 905) IDS 

GO TO 850 

WRITE (5? 9 10) IGSB(l) 

GO TO 850 

WR I TE ( 5 9 920 ) I DS 

GO TO 850 

WRITE <5> 925) IDS 

GO TO 850 

WRITE(5y930)I0SB(l) 
CALL EXIT 



FORMAT ( 
FORMAT ( 
FORMAT ( 
FORMAT ( 
FORMAT ( 
FORMAT ( 
END 



DIRECTIVE 
DIRECTIVE 
I/O ERROR 
DIRECTIVE 
DIRECTIVE 
I/O ERROR 



:rror 
:rror 



on 

ON 

ON READ » 
ERROR ON 



READ* CODE * ' 
1ST WAIT* CODE 
CODE * 'yI4) 
WRITE* CODE = 



ERROR ON 2ND WAIT y CODE 
ON WRITE y CODE « 'vI4) 



14) 

- 'yI4) 

yI4) 

= 'rI4) 



Run Session 



>RUN ASYNCQ 

afocdef £hK JHK JHKHFRTEWawryuy iupoZCVcvbvcnbMBNM7 ( 8534243 " i ' 
abcdef ghkJhkJhkhf rtewcwryuyiupozcvcvbvcribmbriiri7 (8534243 " ♦ ' 



Example 3-2 Asynchoronous I/O Using Event Flags 
for Synchronization (Sheet 2 of 2) 
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TERMINAL I/O 



Device Specific Functions 

In the following discussion, references to function codes and 
subfunction codes are made via the global symbols used when 
programming in MACRO. This is done because all references in the 
literature to these codes use the MACRO symbols. Several examples 
of how to use these in FORTRAN programs are shown below. 

Some device specific function codes are listed in Table 3-3, shown 
below. Table 2-3 in section 2.3 (on the QIO macros) of the 
RSX-11M/M-PLUS I/O Driver's Reference Manual lists all of the 
available special functions for the full-duplex terminal driver. 
As noted, some of these functions are SYSGEN options. Many of the 
device-specific functions are selected using subfunction codes. 
These codes may be ORed with standard or device-specific function 
codes to produce special functions. For instance, the subfunction 
TF.TMO (read with timeout) may be ORed with a read function such 
as IO.RLB to produce a function of "read logical block with 
timeout . " 

The octal values for IO.RLB and TF.TMO are 1000 and 200, 
respectively; hence the combination of the two functions is 
represented by the octal value 1200. 

This can coded in FORTRAN as follows: 

CALL QIO ("1200, , , , , , ,) 

or, to improve readability: 

INTEGER TFTMO 

DATA TFTMO/" 200/ 

DATA IORLB/"1000/ 

CALL QIO(IORLB. OR. TFTMO, ,,,,,, ) 

Another way to produce this function which you may find simpler 
is : 

INTEGER RLBTMO 
DATA RLBTMO/" 1200/ 
CALL QIO (RLBTMO ,,,,,,,) 
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Table 2-4 in Chapter 2 of the I/O Driver's Reference Manual lists 
the various combinations which are possible. For example, TF.TMO 
(read with timeout) ORed with a read function (IO.RLB, 10. RPR, 
IO.RNE, etc.) terminates the read if the specified time period 
goes by between keystrokes. For additional information on the 
device-specific function codes, see section 2.3.2 (on 
Device-Specific Functions) in the RSX-11M/M-PLUS I/O Drivers 
Reference Manual . Examples of the use of Read After Prompt, Read 
No Echo, and Read With Timeout are included in this module. 

Note that if you use subfunction codes with read or write function 
codes, you should use logical operations rather that virtual; 
i.e., use IO.RLB and IO.WLB rather than IO.RVB and IO.WVB. The 
reason for this is that when a virtual operation is requested on a 
terminal, the Executive converts the operation to a logical 
operation. In the process, any subfunction codes are lost. 



I/O Status Block and Terminating Characters 

As for other I/O functions, the low-order byte of the first word 
of the I/O status block contains the I/O status byte, indicating 
the success or failure of the I/O operation. Also, the second 
word contains the count of characters actually transferred. For 
reads from a terminal, the high-order byte of the first word of 
the I/O status block contains the terminating character in ASCII 
(<RET>, CTRL/C, etc.) for successful reads. Normally, CTRL/Z is 
treated as an error. The I/O status byte is set to IE. EOF (-10.) 
and the character count contains the count of characters read 
before the CTRL/Z. 

Example 3-4, which follows, shows how CTRL/Z can be handled 
specially in a program. Two special function codes, IO.RST and 
IO.RTT, allow reads to be successfully terminated by nonstandard 
terminating characters. The first allows any non-alphanumeric 
character to terminate input; the second allows the user to 
specify which character or characters should terminate the read. 
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Table 3-3 


Some Special Terminal Function Codes 


Global 
Symbol 


Octal 
Value 


Function 


I/O Parameter 
List 


IO.RNE 


001020 


Read With No Echo 
(Same as IO.RLB! TF.RNE) 


<stadr , size [ , tmo] > 


10. RPR 


004400 


Read After Prompt 


<stadr,size, [tmo] , 
pradr ,prsize , vf c> 


IO.RST 


001001 


Read With Any 
Special Terminators 
(Same as IO.RLB! TF.RST) 


<stadr , size [ , tmo] > 


IO.RTT 


005001 


Kcdu winn bpeciEiea 
Special Terminators 


sstaar r si ze r Lumoj r 
table> 


IO.WBT 


000500 


Write Logical Block, 
through ongoing I/O 
(Same as IO.WLB! TF.WBT) 
Task must be privileged 


<stadr , size , vf c> 


none 


001200 


Read With Timeout 
(10. RLB ! TF • TMO ) 


<stadr , size , tmo> 
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Read After Prompt 

The Read After Prompt function allows the combination of a write 
of prompting text followed by a read in a single QIO request. The 
I/O parameter list contains six parameters, three for the read, 
and three for the write. The following notes are keyed to Example 
3-3. 

WTQIO for Read After Prompt. The function code is 10. RPR 
(4400(8)). The first three parameters in the I/O 
parameter list are for the read, the last three are for 
the write. The write is performed first, followed by the 
read. The 44(8) for the vertical format control causes 
the prompt text to appear on the next line, followed 
immediately on the same line by the prompt for the read. 

O Use a normal FORTRAN WRITE to echo the input string. 

Q If the operator types a CTRL/Z, an error status is 
returned. In this case, we just wish to exit normally. 
Therefore, we must check for this condition and handle it 
specially. 

The ability to use certain function codes, including Read After 
Prompt, is dependent on whether the option was included in the 
SYSGEN for your system. Before attempting to use these functions, 
check with your system manager to see if they'are available. 
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PROGRAM PROMPT 

C 

C File PROMPT. FTN 
C 

C This task issues 3 QIO for READ AFTER PROMPT y echo's it 

C and prompts 33s in* This continues until a CNTRL/Z is typed* 

C 

C 



Buffer for prompt string 

READ buffer 

I/O status block 

I/O parameter block 



BYTE PROM < 22) 
BYTE BUFF (80) 
BYTE I0SBC4) 
INTEGER FARM (6) 
EQUIVALENCE < NCHAR y I OSB ( 3 ) ) ! NCHAR is for I/O 

! count 

DATA PROM ! Fill the prompt buffer 

1 /'P' y '1 ' 9 'e' y '3' 9 's' y .'e' y ' ' 9 't' 9 'a' y 'p' y 'e' y 



2 ' ' y ' a ' y ' n ' 9 ' y ' y ' t ' y ' h ' y ' i ' y ' r. ' y 7 3 ' y ' X ' 

DATA I0RPR /"4400/ ! Read after prompt 

C ! function code 

C 

C START? 

C Bet up params* for QIO 



/ 



C 

C 

C 

C 

C 
C 
.10 

C 

C 

.1.5 

C 

C 

100 



CALL GETADR ( FARM < 1 ) y BUFF CD) 
CALL GETADR ( FARM < 4 ) » PROM ( 1 ) ) 
PARM(2) « 80 
PARM(5) = 22 
PARM(6) = 36 



PI is the address 

of BUFF 
P4 is the address 
of the prompt 
P2 is the length of 

the buffer 
P5 is the length of 

the prompt 
P6 is the prompt 
format control 



O CALL WTQIO < I0RPR y 5 * 1 y y IOSB y PARM y IDS ) ! Invoke QIO 
IF< IDS *LT * ) GO TO 100 ! Directive error? 
IF( IOSB(l) * LT* ) GO TO 110 ! I/O error? 

WRITE ( 5 y 1 5 ) ( BUFF ( I ) 1 1 = 1 y NCHAR ) ! Echo i r.put 

! string 

FORMAT < IXy'You typed: 'ySOAl ) ! FORMAT for 

! echo message 
GO TO 10 ! Start over 



TYPE *y 'Directive error on QIO to READ AFTER 
1PR0MPT* DSW = 'yIDS ! Dir error 
CALL EXIT 
C I/O error* Check for ~Z 

:I..10 _ TlF (lOSB(l) .EG* -10) GO TO 150 ! Branch on "Z 
TYPE *y'I/0 error on QIO to READ AFTER PROMPT* 
1 DSW = 'ylOSB(l) ! I/O error 

.1.50 U CALL EXIT 
END 



Example 3-3 Prompting for Input (Sheet 1 of 2) 
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Run Session 



>RUN PROMPT 

Please tape anything: sJkshJHGJHGHFY134435 
You typed: sJkshJHGJHGHFY 134435 
Please type anything* hello there 
You typed* hello there 
Please type anything: "Z 



Example 3-3 Prompting for Input (Sheet 2 of 2) 



Read No Echo 

Read No Echo is used to override the default of echoing each 
character as it is typed. This is used for passwords and other 
private information. Example 3-4 uses this function. The 
following notes are keyed to the example. 

Write prompting text, then leave cursor at that position 
for input. This is done by having '$' as the first 
character in the FORMAT. 

O Read No Echo QIO. Standard read parameters except for the 
function code. , 

O As in the previous example, we display the text typed in, 
preceded by our own message. Since the Read No Echo 
doesn't echo any characters back and hence doesn't move 
the cursor on the screen, we precede the text with a 
carriage return (15(8)) to get the cursor back to the 
start of the line. Else, the NO LONGER A SECRET WORD 
message will begin away from the left-hand margin, after 
the : "SECRET WORD:". 
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PROGRAM NOECHO 

C 

C File NOECHO *FTN 
C 

C This task prompts for input y reads it without echo and 

C then skips to the next line and displays the input 

C text and exits* 

C 

C 



BYTE BUFF (80) y I0SB(4) yCR(l) 
INTEGER FARM (6) 



DATA I0RNE /"01020/ 
DATA CR /"IS/ 



! QIO Read no echo code 

! Carriage return character 



! write prompt 

! Prompt string 

! buffer address 

! Buffer length 



WRITE <5>1> 
.1. FORMAT C$SECRET WORD* ') 

C Set up the I/O parameter list 

CALL GET ADR ( FARM ( 1 ) y BUFF ( 1) ) 
PARM<2) « 80 
C Issue read no echo 

CALL WTQIO ( I0RNE y 5 y 1 y y 10SB y PARMy IDS) 

IF (IDS .LT* 0) GO TO 100 ! Dir error? 

IF (IC)SB(l) ♦ LT ♦ 0) 60 TO 110 ! I/O error? 
WRITE (Sy2) CRy(BUFF(I)yI = lyl'0SB(3)) ! Echo input 
2 FORMAT (' 'yAly'NO LONGER A SECRET WORDf ' y 80 A 1 ) 

CALL EXIT 

C 

C Error conditions 

c 

100 TYPE *y "DIRECTIVE ERROR ON READ* STATUS ~ 'yIDS 

CALL EXIT 

.1.10 TYPE *y 'I/O ERROR ON READ* CODE « 'ylOSB(l) 

CALL EXIT 
END 



Run Session 



>RUN NOECHO 
SECRET WORD ♦ 

NO LONGER A SECRET WORD ♦ ADD 



Example 3-4 Read No Echo 
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Read With Timeout 

Example 3-5 is a repeat of Example 3-1, but with a timeout on the 
read. The following notes are keyed to the example. Note 2 is in 
the run session. 

To invoke the timeout mechanism, TFTMO is ORed with the 
read function (IORLB) . We must use Read Logical Block 
here, because any subfunction bits are stripped off when a 
Read Virtual Block is translated to a Read Logical Block 
function. In addition, the third parameter in the I/O 
parameter list specifies the length of the timeout in 
10-second intervals. This timeout occurs if that amount 
of time passes between successive keystrokes. If a 
timeout occurs, input is terminated, but no error is 
reported. Instead, the success code +2 is returned rather 
than the standard +1. 

In the first run, the QIO timed out after KJHKJjjj. In 
the second run, the QIO was terminated with a carriage 
return before it timed out. 

To handle the timeout specially, just check the I/O status 
byte for a value of +2 (IS.TMO). Another alternative for 
placing a time limit is to use a Mark Time directive (CALL 
MARK). The timeout with a Mark Time is for the entire 
input, rather than for the next keystroke. 
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PROGRAM QI.OTIM 



QIOTIM.FTN 



This task reads 3 line of text from the terminal y 
converts all upper case characters to lower case? and 
prints the converted message back at the terminal* It 
uses synchronous QlOsy with a timeout on the read* 



C+ 

C FILE 

C 
C 

C 

c: 

C 
C- 



INTEGER IQSB<2) yPLIST<3> yDSWyDRCTV 
BYTE BUFF < 80 ) y SUCCOD 
EQUIVALENCE (SUCCOD? I OSB) 



Success code 
byte of I/O 
block 



is low 
status 



MNEMONICS 

INTEGER lORLBy TFTMOy IGUIVB 

DATA I0RLB ? TFTMGy l'GWVB/ "1000 » "200? 



11000/ 



CALL GETADR < PL I ST y BUFF ) 
PL 1ST (2) = 80 
PL I ST (3) •= 1 

CALL WTQIO ( I0RLB ♦ OR ♦ TFT MO y 5 y 1 y y I0SB y 

! Issue read 



Fill in buffer address 
Length of buffer 
Timeout count 

ISTyDSW) 



IF <DSW*LT*0> GOTO 1001 ! Branch on 
IF <SUCC0D*LT.0> GOTO 1011 ! Branch 



Check 
and Z 



DO 10 I=1*I0SB(2> 



for uppercase ASCII 



! Get count 
! typed in 
character? must 



C It is 



10 



IF < BUFF < I > ♦ LT ♦ ' A ' ♦ OR ♦ BUFF ( I ) ♦ GT * ' Z 
upper csse» so convert 



d:i. r error 
on I/O error 

of characters 

be between A 

) GOTO 10 



BUFF ( I ) •• 
CONTINUE 
PL I ST (2) 
PL I ST (3) 



BUFF < I > +32 



I0SBC2) ! Character count and 

"40 ! Format control for 

! output 

CALL WTQ 1 < I OW VB y 5 » 1 ? y I OSB y PL I ST y DSW ) ! Output 

! results 

IF <DSW,LT*0) GOTO .1.002 ! Branch on dir error 
IF <SUCC0D*LT»0) GOTO 1012 ! Branch on I/O error 
CALL EXIT 



Example 3-5 Read With Timeout (Sheet 1 of 2) 
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C 

C Error code 
C 

.1.001 DRCTV = 1 ! Error on 1st QIO 

GOTO 1003 ! Print message and exit 

.1.002 DRCTV 2 ! Error on 2nd QIO 

.1.003 TYPE 1004* DRCTV yDSW 

.1.004 FORMAT <' DIRECTIVE ERROR ON DIRECTIVE *'»I2r'» 
1 DSW -'9 16) 
CALL EXIT 

1011 DRCTV « 1 ! Error or. 1st QIO 

GOTO 1013 ! Print message and exit 

1012 DRCTV = 2 ! Error on 2nd QIO 
.1.013 TYPE 1014 * DRCTV * 1'OSBd ) 

1014 FORMAT <' I/O ERROR ON DIRECTIVE *'>I2r'r I/O 
1C0DE ='»I6) 
CALL EXIT 
END 



Run Session 



">RUN QIOTIM 
KJHKJJJJ 

k JhkJ JJ J 
>RUN QIOTIM 
J J Jaf hk Jf i u r <RET> 
JJJaf hk Jf iur 



Example 3-5 Read With Timeout (Sheet 2 of 2) 
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Terminal-Independent Cursor Control 

Terminal-independent cursor control is provided if selected at 
SYSGEN time. If this is done, certain I/O requests are 
automatically converted for you by the terminal driver for the 
particular device for which the I/O request is made. This is 
typically done with escape sequences used for positioning the 
cursor. This allows a task to move the cursor to any position on 
the screen and then write a message. This also can be done by 
imbedding the terminal-specific escape sequences into the write 
buffer. The advantage of using terminal-independent cursor 
control is that the same program will work at different terminals 
(VT-52s and VT-100S, for example), without any need for 
modification. 

To provide cursor control, place the proper value in the vertical 
forms control word of the I/O parameter list. If the high-order 
byte in the VFC word is nonzero, the word is interpreted as a 
cursor position. The high-order byte is the line number, and the 
low-order byte is the column number. Home position, the upper 
left corner of the screen, is defined as line 1, column 1. To 
start the display at line 10, column 25, place a 10 in the 
high-order byte and a 25 in the low-order byte. To do this, use 
the expression 10*256 . OR. 25 . In general, X*256 • OR. Y corresponds 
to position X,Y on the screen. If the high-order bit in the line 
number byte is set, the screen is cleared before the cursor is 
moved. 
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Example 3-6 demonstrates the use of terminal-independent cursor 
control. The following notes are keyed to the example, 

Issue a Mark Time directive. In the CALL MARK (3,1,3, DSW) , 
the first parameter is EFN 3. The 1 is the time interval 
magnitude. The second 3 is the time interval unit. A 3 
indicates minutes. Hence the directive will set EFN 3 in 
one minute. 

Issue the second Mark Time directive. This one will set 
event flag 2. It is used as the time interval for 
updating the time. When the one second goes by and the 
flag is set, we check for one minute gone by and update 
the time display again if it has not. 

O Put the address of TIMMSG into PLIST(l). 

O Put X (line) in high byte and Y (column) in low byte of 
PLIST(3), which is the vertical forms control for a QIO. 
When the high-order byte of the VFC is nonzero, the word 
is interpreted as a cursor position. 

O Issue the write. The vertical format control (X*256) .OR.Y 
places the cursor before the write at line X, column Y. 
The TF.RCU subfunction code (TFRCU) instructs the terminal 
driver to save the cursor position before moving it and 
then to restore it after writing the message. This allows 
an operator to continue typing in commands while this task 
runs . 

O Wait for one second to go by. 

O Read event flag 3. If it is set, the one minute is up and 
we should exit. 

The display will actually appear at line X, column Y on the 
screen, and is updated every second. 
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PROGRAM DATUM 
FILE DATTIM.FTN 

This task Pisces the date and the time at line Xy 
column Y and then updates the display every Z seconds 
for 1 minute* 

INTEGER XyYyZ 

DATA Xy YyZ/5y32yl/ 

INTEGER DSW t IGSB ( 2 ) y PLIST < 3 ) 

BYTE SUCCOD y TIMMSG < 18 ) 

EQUIVALENCE ( SUCCOD t IOSB ) ! Low byte of status 

! block is success code 
INTEGER IOWLB y TFRCU 1 1 SCLR 
DATA lOWLBvTFRCUylSCLR/MOOylyO/ 



C 



CAL 



MARK ( 3 y 1 y 3 y DSW ) 



10 



IF (DSW.LT.O) GOTO 1001 
CALL MARK ( 2 y Z y 2 y DSW ) 

IF (DSW.LT.O) GOTO 1002 
CALL DATE (TIMMSG) 
TIMMSG(IO) = ' ' 



CALL TIME (TIMMSG (11) ) 
CALL GET ADR ( PL I ST y T IMMSG ) 

PLIST (2) = 18 
PL I ST ( 3 ) = ( X*256 ) ♦ OR * Y 
Display time 

CALL WTO 10 ( IOWLB ♦ OR ♦ TFRCU y 

IF (DSW.LT.O) GOTO 1003 ! 

IF ( SUCCOD U..T.O) GOTO 1004 



Set up to exit after 

1 minute 
Branch on dir error 
Set event flask 2 after 

Z seconds 

Get date in bytes 1-9 
Insert space between 

date and time 
Get time in byte 11-18 



CALL WAITFR(2yDSW) 

IF (DSW»LT*0) GOTO 1005 
Check for 1 minute sJone by 

CALL READEF(3yDSW) ! 
IF (DSW.LT.O) GOTO 1006 ! 
IF (DSW. ECU I SCLR) GOTO .1.0 



GOTO 1100 



5 y 1 y y I OSB y PL I ST y DSW ) 

Branch on dir error 

! Branch on I/O 
error 

Wait for mark time to 

ex pi re 

Branch on dir error 

Check event f las* 
Branch on dir error 
! Check for flag 
already clear. If 
clear y minute 
not up yety update 
display ada in 



Example 3-6 Terminal-Independent Cursor Control (Sheet 1 of 2) 
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C Error 


code 








1001 


WRITE (5? 


1051 ) 


DSW 






GOTO 1100 








1002 


WRITE <5y 


1052) 


DSW 






GOTO 1100 








1003 


WRITE (5? 


1053) 


DSW 






GOTO 1100 








.1.004 


WRITE <5» 


1054) 


SUCCOD 






GOTO 1100 








1005 


WRITE <5* 


1055) 


DSW 






GOTO 1100 








1006 


WRITE (5*1056) 


DSW 






GOTO 1100 








1051 


FORMAT (' 


ERROR 


ON MARK TIME FOR 1 MINUTE* 


DSW ~ 




1 'j-15) 








1052 


FORMAT < ' 


ERROR 


ON MARK TIME FOR 1 SECOND* 


DSW - 




1 'vI5) 








1053 


FORMAT (' 


HI RECTI ME ERROR ON WRITE ♦ DSW * 


' r 15) 


1054 


FORMAT (' 


I/O ERROR ON WRITE ♦ CODE = '*I5> 




1055 


FORMAT <' 


ERROR- 


ON WAIT FOR* DSW = '*I5) 




1056 


FORMAT ( ' 


ERROR 


ON CLEAR EVENT FLAG* DSW = 




1100 


CALL EXIT 










END 








Run Session 














12-MAR-82 11:12:54 





>RUN DATTIM 



! DISPLAY WILL START AT LINE 5* COLUMN 32 



Example 3-6 Terminal-Independent Cursor Control (Sheet 2 of 2) 



Now do the tests/exercises for this module in the Tests/Exercises 
book. They are all lab problems. Check your answers against the 

solutions provided, either in that book or in on-line files. 

If you think that you have mastered the material, ask your course 

administrator to record your progress in your Personal Progress 

Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, return 

to this module for further study. 
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USING DIRECTIVES FOR INTERTASK COMMUNICATION 



INTRODUCTION 

The RSX-11M program development features allow modular development 
of programs; the multitasking feature allows a modular approach 
to applications. 

A system of multiple tasks may require one or more of the 
following services provided by executive directives under RSX-11M. 

• First task requests that the second task be run. 

• First task is notified of completion of the second task 
operation. 

• Tasks pass data to each other. 

This module explains how to use system directives for this type of 
coordination between tasks. 



OBJECTIVES 

• To use directives which control task execution to 
synchronize cooperating tasks 

• To use the send/receive directives to pass data between 
tasks 

• To write tasks which spawn subtasks using parent/offspring 
di rectives 



RESOURCE 

• RSX-11M/M-PLUS Executive Reference Manual , Chapters 2 and 
4 plus specific directives in Chapter 5 
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USING TASK CONTROL DIRECTIVES AND EVENT FLAGS 

It is generally good programming practice to divide a single 
complex task into a number of separate tasks, with each task 
performing a distinct logical function. The use of a group of 
tasks to perform a complex function frequently makes good sense, 
especially where different parts of the process may run at widely 
differing speeds, each more or less independent of the others. 

Suppose, for instance, that one needs to simulate customer 
transactions at a bank. There are, say, five windows and up to 15 
customers can physically stand in line at a time, given the size 
of the waiting area. One might design a group of tasks, one task 
per line, to simulate this complex system. This approach has the 
advantage of simulating the related, but essentially parallel, 
processes in a more realistic manner than would a single, serial, 
simulation. A further advantage of a multitasking approach to 
such a job is that changes in the behavior of the system that are 
caused by changes in a single line (e.g., by assigning different 
sorts of transactions to different lines) can be easily simulated 
merely by modifying the task that simulates that line. 

An RSX-11M programmer typically uses a mix of four multitasking 
methods: 

• Common or group global event flags, together with 
synchronization and task scheduling directives, are used 
to synchronize tasks. 

• Resident commons are used to share data in memory. 

• Memory management directives are used to create and/or 
share data areas dynamically at run time. 

• File handling routines are used to open disk files for 
shared access . 

The use of shared regions, memory management directives and files 
are covered in later modules. 
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Directives 

Table 4-1 lists the various task control directives which are 
available for task synchronization. Most of them were discussed 
in earlier modules. All of the directives are documented 
individually in Chapter 5 of the RSX-11M/M-PLUS Executive 
Reference Manual . 

Table 4-2 shows the differences between suspending and stopping a 
task. The major difference is that stopping puts the task into a 
stopped state which effectively lowers the task priority to 0, 
allowing any active task to checkpoint it if it is checkpointable. 
Suspending or waiting, on the other hand , keeps the task competing 
for memory space on the basis of its running priority. This means 
that if the task is checkpointable, only tasks of higher priority 
can checkpoint it. Waiting for an event flag affects 
checkpointability the same way as suspending. 

Table 4-3 lists the various event flag directives which are 
available for synchronization. 
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Table 4-1 Task Control Directives 
and Their Use for Synchronizing Tasks 



Directive 



Example of Use for Synchronization 



FORTRAN CALL 



REQUES 
RUN 



ABORT 

SUSPND 
STOP 



RESUME 
USTP 



Issuing task activates target task; 
target task then performs some operation 
for issuing task 

Issuing task aborts target task 

A task suspends or stops itself to 
wait for completion of another 
task operation 

A task suspends or stops itself 
until it is needed by another task 

A task resumes or unstops another 
task which has suspended or stopped 
itself while waiting for it 
to complete some operation 



A task resumes or unstops another 
task when it needs the other task's 
services 

A task can also be resumed: 

- by its own AST routine 

- by an operator using a DCL CONTINUE 
command (RESUME in MCR) 



A task can also be unstopped: 

- by its own AST routine 

- by an operator using a DCL START 
command (UNS in MCR) 
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Table 4-2 Stopping Compared to Suspending or Waiting 



Stopping 



Suspending or Waiting 



Priority is effectively 
dropped to 

Task can be checkpointed 
by any other task (if 
checkpointable) 

Likelihood of being 
checkpointed increases. 

Frees memory for other 
tasks 



Task response time 
increases dramatically 
if task is checkpointed 



Priority remains unchanged 



Task can be checkpointed 
only by tasks of higher 
priority 

Likelihood of being check- 
pointed remains normal 

Continued allocation of 
memory can block out lower 
priority tasks 

No change in task response 
time, because no change 
in likelihood of being 
checkpointed 
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Table 4-3 Event Flag Directives and 
Their Use for Synchronizing Tasks 



Directive 



Example of Use for Synchronization 



FORTRAN CALL 



CLREF 



SETEF 



WAITFR 
STOPFR 



STLOR 
WFLOR 

READEF 



A task clears the event flag, then waits 
for it to be set by another task 

A task performing an operation for 
another task sets an event flag to 
signify completion of the operation 

A task waits for completion of an 
operation by another task by waiting 
or stopping for that task to set an 
event flag 

A task waits or stops for the completion 
of the first of some set of operations 

A task tests for completion of an 
operation by another task, without 
waiting or stopping for it 
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Example 4-1 shows the use of the Request Task (REQUES) , Suspend 
(SUSPND) , and Resume (RESUME) directives for synchronization. The 
following notes are keyed to the example. Notes 1,2 and 5 are in 
TASKA. Notes 3 and 4 are in TASKB. 

Q TASKA requests TASKB. This means that TASKB must be 
installed under the name TASKB. After this, both tasks 
are active and compete for memory and CPU time. 

Q TASKA suspends itself. After this it still competes for 
memory at its regular priority, but not for CPU time. 

Q TASKB types out a message and then resumes TASKA. More 
typically, TASKB would perform some service for TASKA 
rather than just typing a message. After TASKB resumes 
TASKA, they both compete for CPU time again. 

Q TASKB displays another message and then exits. 

Q TASKA, now resumed, displays a message and exits. 

Depending on the relative priorities of TASKA and TASKB and on the 
particular task scheduling options on your system (e.g., round 
robin scheduling, etc.), steps 4 and 5 may be reversed on the 
run session. 
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PROGRAM TASKA 

C 

C FILE TASKA ♦FTN 
C 

C This task reauests TASKB to run? and then suspends 

C itself* TASKB resumes this task and exits* 

C 

C Install and run instructions* TASKA and TASKB must he 

C installed* Just run TASKA* 

C 

INTEGER DSW 
DATA TASKB/5RTASKB/ 
C ■ 
TYPE * 9 ' TASKA BEGINS AND REQUESTS TASKB ' 
CALL REQUES ( TASKB * v DSW ) 
IF <DSW*LT*0) GOTO 900 

C 

TYPE *, 'TASKA IS SUSPENDING ITSELF" 
CALL SUSPND(DSW) 

IF <DSW*LT*0) GOTO 910 

C 

©[TYPE *, 'TASKA HAS BEEN RESUMED ' 
[call EXIT 

900 TYPE * y ' TASKA UNABLE TO REQUEST TASKB* DSU = 

1 1 DSW 
GOTO 1000 

910 TYPE tv 'TASKA UNABLE TO SUSPEND* DSW « '*DSW 

1000 CALL EXIT 
END 



Example 4-1 Synchronizing Tasks Using Suspend and Resume 

(Sheet 1 of 2) 
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PROGRAM TASKB 

C 

C FILE TASKB ♦FTN 
C 

C This task is activated by TASK A* It performs its 
C operation and resumes TASK A* which has suspended 
C itself* 
C 

INTEGER DSW 

DATA TASKA/5RTASKA/ 

C 

C START ♦ 

C Any operation could be performed here? but in this 

C case it's only a typeout* 

C 

©[TYPE *? 'TASKB IS ALIVE AND RUNNING ' 
[CALL RESUME < TASKA y DSW ) 
IF <DSW*LT*0) GOTO 900 

OpTYPE *f 'TASKB HAS RESUMED TASKA AND IS EXITING' 
[CALL EXIT 

900 TYPE * 9 ' TASKB UNABLE TO RESUME TASKA* DSW « '»DSW 

CALL EXIT 
END 



Run Session 

>INS TASKA 
>INS TASKB 
>RUN TASKA 

TASKA BEGINS AND REQUESTS TASKB 
TASKA IS SUSPENDING ITSELF 
TASKB IS ALIVE AND RUNNING 
TASKA HAS BEEN RESUMED 

TASKB HAS RESUMED TASKA AND IS EXITING 



Example 4-1 Synchronizing Tasks Using Suspend and Resume 

(Sheet 2 of 2) 
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Example 4-2 shows the use of event flags for synchronization. In 
Module 2, there is a similar example. Here, TASKC requests TASKD, 
rather than requiring an operator to start both tasks. Also, Stop 
For Single Event Flag is used rather than Wait For Single Event 
Flag. The difference between the two is that the first causes the 
task to enter a stopped state and the other causes the task to 
enter a Wait For (like a suspended) state. The following notes 
are keyed to the example. Notes 1,2,3 and 6 are in TASKC. Notes 
4 and 5 are in TASKD. 

Clear the event flag to initialize it. It's initial state 
is unpredictable, since other tasks may have set or 
cleared it. 

Request TASKD. 

Stop until the event flag is set by TASKD. 

TASKD displays a message and sets the event flag. 

TASKD displays a message and exits. 

TASKC displays a message and exits. 

Depending on the relative priorities of the two tasks, significant 
events in the system, and other scheduling considerations, the 
order of the steps may vary. In particular, steps 3 and 4 
above may be reversed, as well as 5 and 6 . 

The event flag must be a common or group global, and not a local 
one. In either case, the users on the system must coordinate to 
avoid several users using the same event flag for different 
purposes. If a group global event flag is used, the flags for 
that group may have to be created using either the Create Group 
Global Event Flags directive (CRGF) or the DCL SET 
GROUPFLAGS/CREATE (FLA /CRE in MCR) command. 

The Executive only scans the Active Task List and schedules tasks 
for CPU time after a significant event. Setting an event flag 
does not cause a significant event. This means that TASKC 
normally won't compete for CPU time until at least the next 
significant event in the system. If it is important that TASKC 
being executing sooner than that, TASKD should issue the Declare 
Significant Event directive (DECLAR) , causing the Executive to 
reschedule tasks. For a discussion of significant events, see 
Chapter 2 of the RSX-11M/M-PLUS Executive Reference Manual. 
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PROGRAM TASKC 
FILE TASKC J-TN 

This task clears an ©vent flag and requests TASKD to 
run* and then stops until the event flag is set by 
TASKD 

Install and run instructions* TASKEi must be installed* 
Just run TASKC* 



INTEGER DSW y FLAG 

DATA FLAG/33/ 

DATA TASKD/5RTASKD/ 



! MNEMONIC FOR EVENT FLAG 



TYPE *y 'TASKC BEGINS AND REQUESTS TASKD' 
CALL CLREF < FLAG y DSW ) 

IF (DSW.LT. 0) TYPE *, 'TASKC UNABLE TO INITIALIZE 
1 EVENT FLAG* DSW « '»DSW 



CALL REQUES ( TASKD y y DSW ) 

IF <DSW*LT*0) TYPE *y 'TASKC UNABLE TO REQUEST 
1 TASKD* DSW « 'yDSW 

TYPE *y 'TASKC IS WAITING FOR EVENT FLAG' 
CALL STOPFR ( FLAG y DSW ) 

IF (DSW*LT*0) TYPE *y'TASKC"S WAIT REQUEST 
1 REJECTED* DSW = 'yDSW 

TYPE * 9 ' TASKC HAS BEEN UNSTOPPED AND WILL NOW 
1EXIT' 

L. L. In. X X T* 
END 



Example 4-2 Synchronizing Tasks Using Event Flags 
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PROGRAM TASKD 

C 

C FILE TASKD* FIN 
C 

C This task is activated by TASKC* It performs its 

C operation and sets the flas* for which TASKC is waiting 

C 

INTEGER DSW y FLAG 

DATA FLAG/33/ ! MNEMONIC FOR EVENT FLAG 

C 

C START i 
C 

C Any operation could be performed here? but in this 

C c a s e i t ' s o n 1 y a t y p e o u t ♦ 

C 

f% [TYPE * 9 ' TASKD IS ALIVE AND RUNNING ' 
W [CALL SETEF ( FLAG 9 DSW ) 

IF <DSW*LT.O> TYPE *>' TASKD UNABLE TO SET EVENT 

1.FLAG ♦ DSW ™ "*DSW 

EYPE * 9 ' TASKD HAS SET THE EVENT FLAG AND IS 
EXITING ' 
ALL EXIT 
END 



Run Session 



>INS TASKC 
>RUN TASKC 

TASKC BEGINS AND REQUESTS TASKD 
TASKC IS STOPPING FOR EVENT FLAG 
TASKD IS ALIVE AND RUNNING 

TASKD HAS SET THE EVENT FLAG AND IS EXITING 
TASKC HAS BEEN UNSTOPPED AND WILL NOW EXIT 



Example 4-2 Synchronizing Tasks Using Event Flags 

(Sheet 2 of 2) 
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SEND/RECEIVE DIRECTIVES 



General Concepts 

The Send and Receive directives are used to transmit a 13 word 
block of data between tasks. The sequence of events is as 
follows: 

1. A task issues a Send Data request, specifying a receiver 
task and a data buffer. 

2. The Executive copies the data buffer into a data packet in 
the dynamic storage region (DSR or pool). 

3. The Executive places the data packet FIFO 
(first-in-first-out) into the receive queue of the 
specified receiving task. 

4. Later, the receiving task issues a Receive Data request, 
specifying a data buffer. 

5. The Executive copies the data packet into the buffer 
specified by the receiving task. 



Directives 

Table 4-4 lists the Send Data directive and the various Receive 
Data directives. The difference among the Receive Data directives 
concerns what happens if there are no data packets in the 
receiver's receive queue. 

All receive directives receive 15(10) words, including the sender 
task name (in Radix-50 format) plus the data. If no sender task 
is specified in a Receive Data directive, the first packet in the 
receive queue is dequeued, regardless of which task sent it. If a 
sender task is specified, only a packet sent by that task is 
dequeued . 
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DIRECTIVES 


FOR 


INTERTASK COMMUNICATION 


Table 


4-4 The 


Send/Receive Data Directive 


Directive 
Name 


Di rective 
Call 


Notes 


Send Data 


SEND 




Sends a 13(10) word 
buffer to receiver 

Event flag (if used) 
set when packet queued 
to receiver 


Receive Data 


RECEIV 




Error if no data 
packets queued 


Receive Data 
or Exit 


RECOEX 




Exit if no data 
packets queued 


Receive Data 
of Stop 


RCST 




Stop if no data 
packets queued 



Synchronizing Send Requests With Receive Requests 

Event flags can be used for synchronization. The event flag is 
specified by the sending task. This event flag is set when the 
data packet has been queued to the receiving task. Thus, a global 
or group global event flag may be used to unblock a receiving task 
which is active and waiting for the event flag to be set. 

In addition, the task control directives can be used for 
synchronization. Table 4-5 summarizes the various synchronization 
techniques which might be used. Keep in mind that a Receive Data 
directive (RECEIV) causes an error condition (DSW = -8, IE. ITS; 
directive inconsistent with task state) if there is no data packet 
in the receive queue. Receive Data or Stop (RCST) and Receive 
Data or Exit (RECOEX), on the other hand, cause the task to stop 
or exit, respectively, if there is no data queued. For further 
information about possible synchronization problems, see the 
writeup on the Receive Data directive (RECEIV) in Chapter 5 of the 
RSX-11M/M-PLUS Executive Reference Manual. 
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Table 4-5 Methods of Synchronizing a Receiving Task 
(RECEIV) with a Sending Task (SEND) 



Method 



Advantages 



Disadvantages 



RECEIV issues a Wait 
For or a Stop For 
Event Flag directive, 
followed by a Receive 
directive. SEND uses 
that (common or group 
global) event flag in 
its SEND directive. 



Low system scheduling 
overhead . 



Requires care in 
initializing and 
setting flag. 
(See Examples 4-3 
and 4-4.) 



RECEIV issues a 
Suspend or a Stop 
directive followed 
by a Receive direc- 
tive. SEND issues a 
Send directive 
followed by a Resume 
or an Unstop 
directive . 

RECEIV issues a 
Receive Data or Stop 
directive. SEND issues 
a Send followed by an 
Unstop directive. 



RECEIV monitors an 
event flag periodi- 
cally. When the 
event flag is set, 
RECEIV issues the 
Receive directive. 
SEND specifies that 
event flag in its 
Send directive. 



Does not require an 
event flag. 



Low system scheduling 
overhead . 

Does not require an 
event flag. 



RECEIV can continue 
processing in para- 
llel with RECEIV. 



Possible problems 
in sequence of 
Suspend or Stop, 
and Resume or 
Unstop, if the 
Resume Unstop is 
issued before the 
receive suspends 
or stops. 

Possible delay 
starting RECEIV 
again, if RECEIV 
was checkpointed . 
(Can be avoided 
if RECEIV is 
built non-check- 
pointable. ) 

RECEIV must 
periodically re- 
issue a Read 
Event Flag or 
Clear Event Flag 
directive. Requires 
care in initiali- 
zing and setting 
the flag. 
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Examples 4-3, 4-4, and 4-5 show the use of Send and Receive 
directives by a pair of tasks. Examples 4-3 and 4-4 use an event 
flag for synchronization; Example 4-5 uses Receive Data or Stop 
along with Unstop for synchronization. The following notes are 
keyed to Example 4-3. Notes 1, 5, 6 and 7 are in SEND1. Notes 2, 
3, 4, 8, 9 and 10 are in RECV1. 



Q RECV1 must be run first, or else the event flag will 
already be set by SEND1 to indicate that a data packet has 
been sent. In that case, RECV1 will clear the flag and 
wait for it to be set again, and won't realize that a data 
packet is already queued to it. 

Q Use a DO loop with "I" as the message counter. We will 
receive and display three messages and then exit. 

O Initialize the event flag. 

O Wait for the flag to be set after SEND1 sends the data 
packet, placing it in RECV1 ' s receive queue. 

O Get the data to be sent. 

O Send the data and set event flag 33 when the data packet 
is queued to RECV1 . 

O SEND1 exits. 

O Receive data from anyone. 

Q Display a header and the data sent. We skip the first two 
words (four-bytes) of the buffer, which contain the name 
of the sender task in Radix-50 format. 

Q Go through the loop which clears the event flag and 
receives again if we have not yet received three messages. 
If we have, display a message and exit. 
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PROGRAM SEND! 



C 
C 

C 
C 
C 
C 
C 

"C 
> C 

_C 
C 



FILE SEND1 ♦ FTN 

This task prompts 
the data to RECV1 
handled through a 



at TI* for a line of text and sends 
for processing* Synchronisation is 
common event flag* 



Install and run instructions* RECvl must he installed 
and run prior to running SEND1* RECvl continues to run 
until it receives 3 data packets* 



BYTE 
DATA 
DATA 
Prompt for 
"TYPE 



Event fl3g 
Receiver task 



OF 



TEXT* 26 CHARACTERS OR LESS ' 
! Read text 



10 



OO 

C Error 
900 



BUFFER < 26) 
1'EFN /33/ 
RTASK/6RRECV1 / 
input 

[TYPE 'TYPE A LINE 
[READ <5»10> BUFFER 
FORMAT <26A1> 

CALL SEND (RTASK'y BUFFER y IEFN? IDSW) 
IF (IDSW *LT* 0) GOTO 900 ! Branch 
CALL EXIT ! Exit 

code 

TYPE * 9 ' UNABLE TO QUEUE DATA TO RECvl ♦ 

CALL EXIT 

END 



! Send 
on dir 



data 
error 



DSW 



IDSW 



Example 4-3 Synchronizing a Receiving Task Using Event Flags 

(Sheet 1 of 3) 
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PROGRAM RECV1 

C 

C FILE RECV1 ♦ FTN 
C 

C This task receives data from sna sender task <e*g*y 
C RECVl)* It prints the data on TI ♦ ♦ Then it waits for 
C another data packet* It does this until it has received 
C 3 messages and then exits* 
C 

C This task synchronizes with its sender through an 

C event flag* 

C 

C Install and run instructions* RECVl must be installed 

and run before running SEND1* 

C 

INTEGER RBUFFC15) ! Receive buffer 

DATA 1'EFN /33/ ! Event flag 

C 



Lc 



00 DO 100 ]>lv3 



j:ALL CLREF <33»IDSU) ! Clear flag 

If <idsw *ge* o) goto io 

TYPE *y 'ERROR INITIALIZING FLAG* DSW 'y.TDSW 
GOTO 1000 

10 O CALL WAITER <33y.IDSW> ! Wait for a send 
IF (I DSW ♦ EG ♦ .1) GOTO 20 

TYPE KUWAIT DIRECTIVE FAILED* DSW « 'yIDSW 
GOTO 1000 

20 Q CALL RECEIV ( y RBUFFy y IDSW) ! Receive from anyone 
IF (IDSW *EQ* 1) GOTO 30 

TYPE *y "RECEIVE DIRECTIVE FAILED IN "RECVl"* 
1 DSW = 'y.TDSW 
GOTO 1000 

30 ^|fTYPE *y "DATA RECEIVED BY "RECVl"**' 

^ LWR I TE ( 5 y 35 ) ( RBUFF (K) yK~3y 15) 
35 FORMAT <' '»13A2> 

100 Q CONTINUE 

TYPE *y '"RECVl" HAS RECEIVED 3 MESSAGES AND WILL 

1 NOW EXIT' 
1000 CALL EXIT 

END 



Example 4-3 Synchronizing a Receiving Task Using Event Flags 

(Sheet 2 of 3) 



121 



USING DIRECTIVES FOR INTERTASK COMMUNICATION 



Run Session 



>INS RECV1 
>RUN RECV1 
>RUN SEND1 

TYPE A LINE OF TEXT y 26 CHARACTERS OR LESS 
:l. 1 1 1 1 1 1 

DATA RECEIVED BY "RECVl"* 

> 

1 1 1 1 1 1 i 
>RUN SEND1 

TYPE A LINE OF TEXT y 26 CHARACTERS OR LESS 

2222222222222222 

DATA RECEIVED BY "RECVi'J 

>' 

2222222222222222 
>RUN SEND1 

TYPE A LINE OF TEXT y 26 CHARACTERS OR LESS 

3333333333333333333333333 

DATA RECEIVED BY "RECVl'J 

> 

3333333333333333333333333 
"RECV1" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 

> 



Example 4-3 Synchronizing a Receiving Task Using Event Flags 
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If you wish to run the tasks in Example 4-3 in any order, RECV1 
must be modified to receive data packets on startup if SEND1 has 
already sent data. It gets complicated because SEND1 may have 
already sent several data packets. It's also possible that event 
flag 33. was left set by someone else. In that case the Receive 
directive will fail, but we should not abort. Example 4-4 shows 
the modifications which must be made to Example 4-3 to allow the 
tasks to be run in any order. The following notes are keyed to 
Example 4-4. 

We use a flag word (IBEF) to distinguish whether we are 
working on messages sent before or after RECV1 starts up. 
Note that RECV1S must be installed as RECV1 , since SEND1 
sends to RECV1. 

Q Check for event flag set on startup. If it is set, issue 
a Receive. If SEND1 has been run one or more times, the 
Receive will succeed. If SEND1 has not been run yet, the 
flag was set by another task and the Receive will fail. 

Q If the flag was not set, SEND1 hasn't sent any messages 
before we started. Clear the IBEF flag, so we know that a 
Receive failure after the flag is set again is a real 
failure. 

Q In the case of a Receive failure, we check to see if we 
are receiving data packets sent before RECVl started up. 
If we are, we know we have received all data packets 
already queued up before RECVl started executing. 

Q If IBEF is clear, this was a failure after receiving all 
data packets sent before RECV2 started up, so display an 
error message and exit. 

If IBEF is set, we have already received all data packets 
which were queued up before RECVl started up. Now clear 
IBEF and wait for the flag to be set at 40. 

Check to see if we are still receiving data packets sent 
before RECVl started up. If so, Receive again. Keep 
receiving until either we get all three packets or we get 
a Receive failure. If, on the other hand, we have 
received a message sent since startup, clear the flag and 
wait for it to be set again when a new message is sent. 

If a task runs and then exits with data packets in its receive 
queue, those unreceived data packets are flushed from the queue on 
exit. Hence, if SEND1 sent four messages before RECVl was run, 
the fourth message would be lost. 
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C 
C 

c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c: 
c 
c 

•g 

c 
c 
c 
c 
c 



PROGRAM RECV1S. 
FILE RECV1S*FTN 

This task and receives data from any sender task 
(e*g* SEND!)* It prints the data an Tl'** Then it 
waits for another data packet* It exits after 
receiving and displaying 3 messages* 

This task synchronizes with its sender through an 
event flag* Because of this synchronisations' and the 
care we take on startup to get messages already 
sentsf the tasks can he run in any orders' with any 
relative priorities* 

Install and run instructions* RECV1S must be installed 
under the name RECV1 to work with SEND1* 

IBEF is the "before" flags' used to keep track of whether 
we are receiving messages sent before RECVi started up* 
If the event flag is set at startup times' keep receiving 
messages until we get a failure* We then wait until the 



to receive 



again 




flag is set 

sent before RECVI started? 
messages sent before 

INTEGER IBEF t IEFN t RBUFF (15)5- MCNT 



1 means receiving messages 



means finished receiving 



DATA 
DATA 



IEFN 
IBEF 



/33/ 
/I/ 



C Here 



JDATA MCNT /3/ ! 
CALL CLREF (IEFN? IDSW) 
IF (IDSW *LT* 0) GOTO 900 
IF (IDSW *E0* 2) GOTO 50 

et 
40 



Event flag 
Before flag? assume 
there are messages 
Message counter 



Branch 
Branch 



on 
if 



dir error 
flag set 



i f f 1 a g n o t i n i t i a 1 1 y 

OflF (IBEF *EQ* 0) GOTO 
[lBEF*0 
CALL WAITER (33s- IDSW) 
IF (IDSW *LT* 0) GOTO 910 
Get here when the flag is set 

CALL RECEIV ( y RBUFF? $> IDSW) 
IF ( IDSW *EQ* 1) GOTO 80 ! 
on failure of 
A IF (IBEF *E0 

j 
i 

if failure after 
startup 

IBEF=0 ! 
GOTO 40 ! 



40 

C 

50 



C Here 



C 
C 

C Here 
C at 



before flag 
Wait for next 
Branch on dir 



message 
error 



! Receive from anyone 
Branch on directive ok 
Receive directive 
0) GOTO 920 ! Check for failure 
on messages received 
before startup* 
receiving messages already there 



Clear before flag 
Wait for flag to be 



set 



ample 4-4 



A Receiving Task Which Can be Run Before or 
the Sender (Sheet 1 of 3) 
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C Successful receipt 
BO ["TYPE * 9 ' DATA RECEI VED 

WRITE (5? 85) <RBUFF<K) 
FORMAT (' 'yl3A2> 
MCNT-liCNT-l 
-IF (MCNT ♦ EQ ♦ 0) GOTO 
C Set up for another receive 
/IF ( I BET" »NE* 0) GOTO 

C 
C 

e 

CALL CLREF (33* I DSW) 
IF (IDSW *LT, 0) GOTO 
LGOTO 40 



BY "RECVl" : ' 

! Decrement message counter 
100 ! Branch back if not done 

50 ! Check for still 

receiving messages sent 
before startup* If so? 
receive aga in* 
If not? clear flag 
930 ! Branch on dir error 

! Wait for flag set again 



C Here when three messages received 

100 TYPE *y' B RECVl" HAS RECEIVED 3 MESSAGES AND WILL 

1 NOW EXIT' 

CALL EXIT 
C Error code 

900 TYPE %t 'ERROR INITIALIZING FLAG ♦ DSW = ',IDSW 

GOTO 1000 

910 TYPE *y'WAIT DIRECTIVE FAILED* DSW « '>IDSW 

GOTO 1000 

920 [TYPE %f 'RECEIVE DIRECTIVE FAILED IN "RECV1"* DSW 
Q 1 ~ '»IDSW 

Lgoto 1000 

930 TYPE *t 'ERROR RECLEARING FLAG ♦ DSW = 'yIDSW 

1000 CALL EXIT 
END 



Example 4-4 A Receiving Task Which Can be Run Before or After 

the Sender (Sheet 2 of 3) 
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Run Session 

> I NS/ TASK-NAME I RECV1 RECV 1 S 
>RUN SEND! 

TYPE A LINE OF TEXT y 26 CHARACTERS OR LESS 
1111 11 
>RUN SEND1 

TYPE A LINE OF TEXT y 26 CHARACTERS OR LESS 

2222222222 

>RUN RECV1 

> 

DATA RECEIVED BY "RECV1"? 
1111 11 

DATA RECEIVED BY "RECVl": 

2222222222 

RUN SEND1 

TYPE A LINE OF TEXT* 26 CHARACTERS OR LESS 
33333 

> 

DATA RECEIVED BY "RECV1": 
33333 

"RECVl" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 



Example 4-4 A Receiving Task Which Can be Run Before or After 

the Sender (Sheet 3 of 3) 
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Example 4-5 uses Receive Data or Stop in the Receiver and Send 
Data followed by Unstop in the sender. These tasks can be run in 
any order. The potential synchronization problems are 
considerably easier to deal with when using this technique of 
synchronization. We will go through it first for running RECV2 
before running SEND2. Then we will discuss the other 
possibilities. The following notes are keyed to the example. 

We issue a Receive Data or Stop directive. If there is no 
data packet queued, RECV2 stops and must be unstopped by 
SEND1. If, on the other hand, there is a data packet 
queued, we want to receive it. The DSW equals IS.SET(+2) 
if the task was stopped and then unstopped, and equals 
IS.SUC(+1) if a data packet was received. If RECV2 is run 
first, we stop. 

Q SEND2 gets the data and sends it. We do not need to 
specify an event flag in the Send Data directive since we 
use Stop/Unstop for synchronization. 

Q Unstop RECV2. In this order, this directive will 
successfully unstop RECV2 because RECV2 stopped when it 
issued the Receive Data or Stop directive. 

There are two directive errors on UNSTOP which are not 
errors for this set of tasks. Check for these errors and 
if found, assume that everything worked correctly. If 
RECV2 is active but not stopped, it must be receiving 
another packet. In that case, RECV2 will receive this 
packet on the next Receive Data or Stop directive. If 
RECV2 is not active, it has not been run yet. The packet 
is still in RECV2's receive queue and RECV2 will receive 
it when it is activated. The above situation will not 
oceur the first time through if RECV2 is run first. 

If the error is not one of the two errors checked 
for, display an error message and exit. 

Q Check for whether we stopped and unstopped. If so, we 
didn't receive the data packet yet. If not, we did 
receive the data. In this case, if RECV2 is run first, we 
did stop and unstop. 

Q Since we have not yet received the data packet, issue 
another Receive. 

O If there is still nothing in the Receive queue, something 
is wrong. Display an error message and exit. 
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Q After a successful Receive, whether immediately or after 
Stop and Unstop, display the received message. In that 
case, issue another Receive Data or Stop and loop through 
again if we have not yet received three messages. If 
there is another data packet queued, we will receive it. 
Otherwise, we stop until SEND2 sends data and unstops us 
again. 

If SEND2 is run once before RECV2 , then the Unstop directive at 3 
will fail. If in fact RECV2 is not active at all, or is active 
but not stopped, it will dequeue the data packet when it issues a 
Receive. Hence, we check for these conditions at 4 and just 
exit if either condition caused the Unstop error. When we run 
RECV2, we do actually receive a data packet at 1. At 5, 
DSW = +1 (IS. SUC) which means that we received a packet and didn't 
stop. Therefore, we display the data and Receive or Stop again. 
This time we will stop until SEND1 unstops us again. 

If SEND2 is run two or three times before RECV2, any data packets 
already sent are received and displayed. In the case of two sent, 
the third RCDS will cause RECV2 to stop until SEND2 sends a third 
packet and unstops it. In the case of three packets already sent, 
RECV2 will receive all three and then exit. 

As in Example 4-4, if SEND2 sends more than , three packets, any 
additional packets will be lost because the receive queue is 
flushed when the task exits. 
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PROGRAM SEND2 
FILE SEND2*FTN 

This task prompts at TI* for a line of text and sends 
the data to RECV2 for processing* The receiver will 
continue to run until it receives 3 messages* 
Synchronization is handled through RECv"2's stop hit* 
RECV2 and SEND 2 may be run in any order* 

Install and run instructions* RECV2 must be installed* 



10 



20 



BYTE BUFFER (26) 

INTEGER DSW 

REAL RECV2 

DATA RECV2/5RRECV2/ 

INTEGER IE ITS y IE ACT 

DATA IE ITS? IEACT/-8y --7/ 



! Send buffer 



Receiving task name 
Error mnemonics 



! Send data to RECV2 



TYPE # 9 ' TYPE A LINE OF TEXT? 26 CHARACTERS OR LESS 
READ (5*5) BUFFER 
FORMAT (26A1) 

CALL SEND < RECU2 y BUFFER y y DSW ) 

If <dsw*eg*i> goto .1.0 
type * y ' unable to queue data 

lyDSW 

CALL UStP<RECV2»DSW) 
IF (DSW.EQ.l) GOTO 20 
IF <DSW*EQ*IEITS> GOTO 



TO "RECV2 1 



DSW 



Unstop RECV2 
Branch on directive ok 
! Isn't he stopped? 
That ' s ok y he'll pick 
up data when he 
executes RCDS* 
! Is he not active? If 
not y he'll pi ck up 
data when activated 
"RECV2 M * DSW = 'yDSW 
Any other error is bad 
Exit 



IF (DSW*EQ*1'EACT) GOTO 



20 



! 

20 



TYPE *y 'UNABLE TO UNSTOP 



CALL 
END 



EXIT 



Example 4-5 Synchronizing a Receiving Task Using RCDS 
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PROGRAM RECV2 
FILE RECV2 ♦ FTN 

This task receives data from another task (e*g* SEND2), 
It prints the data* along with a header? on TI** Then 
it waits for another data packet? continuing this 
until it has received 3 messages* 

This task synchronizes with its sender using RCST* 
Because of this synchronisation? the tasks can be run 
in any order? with any relative priorities* 

Install and run instructions* RECV2 must be installed* 



INTEGER RBUFFQ5) 
INTEGER DSW?ISSET 
DATA ISSET/2/ 



! Receive buffer 



! DSW code mnemonic 



C 
C 
C 
C 

50 

C 

C 

C 

C 



BO 100? 1=1? 3 
A CALL RCST< ?RBUFF?DSW) 
w IF <DSW*GE*0> GOTO 50 

Type *? 'RECEIVE DIRECTIVE 

1 DSW = '?DSW ! 

GOTO 1000 ! 

Successful receipt or unstopped 
check for unstopped after being 
we has/e to receive the data 

IF <DSW*NE* ISSET) GOTO 60 



! Receive from anyone 



FAILED IN "RECV2" ♦ 
Display error message 
and exit 

by another task* First 
stopped? in which case 

Were we stopped due 
to no data? If not 
<NE) ? we have a 
data packet 



C 

60 

75 C 

100 

C Have 



.1.000 



Stopped due to no data* 

A CALL RECEIV< ?RBUFF? ?DSW) 
w IF <DSW*EQ*1> GOTO 60 

TYPE *? "RECEIVE DIRECTIVE 
1UNST0PPED* DSW = '?DSW 
GOTO 1000 
Display dat3 

TYPE 75? <RBUFF< J) ? J~3? 15) 
FORMAT (' DATA RECEIVED BY " 
CONTINUE 
received 3 messages 
TYPE *? , "RECV2" HAS RECEIVED 
.1 NOW EXIT' 

CALL EXIT ! Exit 

END 



! Now get the packet 

FAILED AFTER "RECV2" 
! Display error 
! message and exit 



RECV2 " ♦ '/1X?13A2> 



3 MESSAGES AND WILL 



Example 4-5 Synchronizing a Receiving Task Using RCDS 

(Sheet 2 of 3) 
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Fs'un Session 



! Run RECV2 first y then run SEND2 3 times 
>.TNS RECV2 
>RUN RECV2 
>RUN SEND2 

TYPE A LINE OF TEXT y 26 CHARACTERS OR LESS 
.1. 11111111 

DATA RECEIVED BY " RECV2 B ♦ 

111111111 

>RUN SEND 2 

TYPE A LINE OF TEXT y 26 CHARACTERS OR LESS 
'J 2.22. 2 

DATA RECEIVED BY "RECV2"i 



>RUN SEND2 

TYPE A LINE OF TEXT r 26 CHARACTERS OR LESS 

3333333333333333333333333 

DATA RECEIVED BY " RECV2 " ♦ 

3333333333333333333333333 
"RECV2" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 



! Run SEND2 once first? then run RECV2y and then run SEND2 twice more 
>RUN SEND2 

TYPE A LINE OF TEXT* 26 CHARACTERS OR LESS 
44444 

>RUN RECV2 

DATA RECEIVED BY "RECV2" ♦ 
44444 

>RUN SEND2 

TYPE A LINE OF TEXT* 26 CHARACTERS OR LESS 
55555555 

DATA RECEIVED BY "RECV2"i 
55555555 
>RUN SEND 2 

TYPE A LINE OF TEXTy 26 CHARACTERS OR LESS 
66 

DATA RECEIVED BY "RECV2 " * 
66 

"RECV2" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 



Example 4-5 Synchronizing a Receiving Task Using RCDS 

(Sheet 3 of 3) 
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Using Send/Receive Directives for Synchronization 

If it is desirable to pass data as well as notify another task of 
the occurrence of an event, the Send/Receive directives can be 
used to perform this double function. The advantage of this 
approach is that data can be sent in addition to notifying the 
other task of the occurrence of the event. The receiving task can 
synchronize with the event using any of the techniques listed in 
Table 4-5. 



Slaving the Receiving Task 

Normally, a task runs under the UIC and the TI: of its initiator, 
the operator issuing the RUN command, or the task issuing the 
Request Task directive (REQUES) . A receiver task which is run 
from the same terminal as the sender is assigned the same UIC and 
TI : as the sender. However, if the receiver is run from another 
terminal or by a different user, it's UIC and/or TI: may be 
different from that of the sender. Also, a receiver might receive 
data from several different tasks initiated at several different 
terminals. 

If it is desirable to have the receiver task take on the UIC and 
the TI: of the sender each time data is received, the receiver 
task can be built as a slaved task. The advantages of this 
approach are that the receiver then acquires the same privileges 
as the sending task and can also do I/O directly to the sending 
task's terminal (through TI : ) . To build a task as a slaved task, 
either task-build with the /SLAVE qualifier or install with the 
/SLAVE qualifier. 
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PARENT/OFFSPRING TASKING 

In multitasking situations, it is often useful to have one task 
activate and monitor other tasks, or monitor already active tasks. 
In particular, the requesting task may wish to receive periodic 
status reports from the other tasks during execution, or when the 
tasks exit. 

For example, a task to secure a nuclear reactor in case of 
accident activates a pair of subordinate tasks, one task to issue 
warnings to personnel and the other to initiate the shutdown 
procedure. The task which activates the two subordinate tasks can 
receive periodic status reports from each of the other tasks, so 
that it can take appropriate action in case of a problem. In 
particular, it would want to know about any failure in either 
operation. 

Under RSX-11M, parent/offspring tasking provides a facility for 
setting tasks up in the structure described above. As we shall 
see, this is easier to program than Send/Receive directives. A 
parent task is one which connects to or spawns another task, 
called an offspring task. 

When a task spawns another task, it both activates the task and 
establishes a connection to it. If the task is already active, a 
parent task should just connect to the offspring. Figure 4-1 
shows this relationship. When a task spawns another task it can 
also send a command line or data of up to 79 characters (or bytes) 
to the offspring. 

Once the connection is established using Spawn or Connect, the 
offspring can send or emit status by using the Emit Status (EMST) 
directive. This allows the offspring to send a one-word status 
value to the parent. Upon exit, a success code (EX$SUC=+1) is 
returned if the standard EXIT is used, or a specified one-word 
status can be returned if the Exit With Status directive (EXST) is 
used. If the task is aborted, a standard severe warning code 
(EX$SEV=+4) is returned. The status is automatically returned in 
a status block in the parent task — no receive directive is 
needed. Synchronization can be handled using event flags or an 
AST routine. The flag is set or the AST routine entered when the 
status is received. Table 4-6 shows the standard status codes. 
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PARENT 



SPAWN OFFSPRING 



OFFSPRING 



COMMAND LINE 



EVENT FLAG AND/OR 
AST ROUTINE 



OFFSPRING STATUS 



EXIT, EXIT 
WITH STATUS, 
OR EMIT 
STATUS 



Figure 4-1 Parent/Offspring Communication Facilities 
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Additional directives are provided for parent/offspring support. 
The Send Data, Request, and Connect directive combines the 
functions of the three separate directives (Send, Request, and 
Connect) into a single directive. This is similar to Spawn, but 
sends a 13 word data packet rather than a 79 byte command line. 
It also just sends data and connects if the task is already 
active. Spawn is rejected if the task is already active, unless 
the task is a CLI (Command Line Interpreter) . 

Two other directives are provided to allow chaining, or passing a 
parent/offspring connection from an offspring to another task. We 
will discuss chaining in more detail later in this module. 



Table 4-6 Standard Exit Status Codes 



Mnemonic 


Value 


Meaning 


EX$WAR 





Warning — task succeeded, but 
irregularities are possible 


EX$SUC 


1 


Success — results as expected 


EX$ERR 


2 


Error — results unlikely to be 
as expected 


EX$SEV 


4 


Severe Error — one or more fatal 
errors were detected, or offspring 
aborted . 



The above symbols could be used in a FORTRAN program by dropping 
the $ sign from the symbol and using them as a variable name with 
the appropriate values. 
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Directives Issued by a Parent Task 

Table 4-7 summarizes the directives which may be issued by a 
parent task. Note that parent and offspring are relative terms, 
an offspring of one task may be the parent of another. 



Table 4-7 Comparison of Parent Directives 









Send, Request 


Characteristic 


Spawn 


Connect 


and Connect 


Lan oe usee tor 


\7 a c 
ICS 


JNO 


ICS 


or t spring wnicn 








is not yet active 








Can be used with 


No, except 


Yes 


Yes 


offspring which 


if offspring 






is already active 


is a Command 
Line Inter- 
preter (CLI) 






Can pass data (or 


Yes (up to 


No 


Yes (13 words) 


command) to off- 


79 bytes) 






spring as part 








of directive* 








Can be used to 


Yes 


No 


No 


pass commands to 








a Command Line 








Interpreter (CLI) 









* If a parent/offspring relationship is established via Connect, 
the tasks can of course exchange data using Send/Receive. The 
table above indicates whether the passing of data from parent 
to offspring is a capability of the directive in and of itself. 
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LEARNING ACTIVITY 

Chapter 4 of the RSX-11M/M-PLUS Executive 
Reference Manual contains a good discussion 
of the Parent/Offspring directives and in 
particular it gives a number of possible uses 
for them. We will not discuss these various 
uses anywhere in this course. 

Read Sections 4.1, 4.2, and 4.3 of the 
RSX-11M/M-PLUS Executive Reference Manual for 
a discussion of the Parent/Offspring 
directives and examples of their use in 
applications. 
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Table 4-8 summarizes the arguments for the Spawn directive, the 
Connect directive, and the Send Data, Request, and Connect 
directive. For additional information, see the writeup on each 
directive in Chapter 5 of the RSX-11M/M-PLUS Executive Reference 
Manual. 



Table 4-8 Directives Used by a Task to 
Establish a Parent/Offspring Relationship 



Directive Directive 
Name Call 



Spawn CALL SPAWN(tsk,grp,mem,efn,ast,esb,param, 

cmdlin ,cmdl en ,unum,dnam,dsw) 

Connect CALL CNCT ( tsk , ef n ,ast , esb ,param ,dsw) 

Send, CALL SDRC (tsk,buf ,efn ,ast ,esb,param,dsw) 

Request , 
and Connect 



tsk - offspring task 

grp,mem - UIC offspring will run under 

efn - event flag to be set when offspring exits or emits 
status 

ast - AST routine to be entered when offspring exits or 
emits status. 

esb - exit status block address 

param - name of a word to receive the status block address 
when the AST occurs 

cmdlin ,cmdlen - address of buffer with command line, 
length of command line 

unum,dnam - device to be TI : for offspring 
buf - 13(10) word buffer to be sent 
dsw - directive status word 
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Example 4-6 shows a task which spawns PIP to display a directory 
at TI : . The following notes are keyed to the example. 

Q The command line to be passed to PIP. We include the 
three character command name to be consistent with the way 
MCR passes commands if a utility command is typed to MCR. 

Q Display startup message* 

Q Spawn ...PIP. Event flag 1 will be set when ...PIP exits 
or emits status. EXSTAT is the address of the eight-word 
status block (only the first word is used) . CMD is the 
starting address of the command line and LEN is its 
length . 

O Wait for event flag 1 to be set when ...PIP exits or emits 
status. Notice that this is a local event flag, local to 
this task, which is cleared by the Executive when the task 
is spawned and set by the Executive when the spawned task 
exits or emits status. 

Q The high-order byte of the exit status code may contain 
unexpected data. Therefore, clear that byte by specifying 
the logical AND of the code and 377(8) before displaying 
the code . 

O On the Run Session - The first run session shows a 
successful exit by ...PIP, the second one shows ...PIP 
aborted by an operator. Note the different status codes. 

NOTE 

On an RSX-11M system, an attempt to spawn 
...PIP will fail if ...PIP is already active. 
This works diffently from initiating PIP from 
MCR, where an attempt is made to install the 
task ...PIP under the name PIPTnn if ...PIP 
is already active. A solution to this 
problem is to spawn CLI... (the current 
CLI) , ...DCL (DCL) or MCR... (MCR) and send 
it the command line. It will in turn start 
up the appropriate PIP task under ...PIP or 
PIPTnn, as if the command was typed in by an 
operator. See section 4.4 (on Spawning 
System Tasks) of the RSX-11M/M-PLUS Executive 
Reference Manual for additional information. 
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PROGRAM SPWN 



C 

C File SPAWN *FTN 



This program spawns PIP* passes it a command line to 
display a directory at Tliy waits for it to exit* and 
then displays its exit status* 



Data 



Code 

o 



C Error 
900 

910 
1000 



INTEGER EXSTAT(S) y PL 1ST < 3) yDSW 
BYTE BUFF (80) 
REAL PIP»CMD<3> 
DATA PIP/6R* ♦ ♦PIP/ 
DATA CMD/'PIP ' 9 '**MA' y 'C/LI'/ 

WRITE (5*15) ! Write 

FORMAT (' SPAWN IS STARTING AND 
CALL SPAWN ( PIP y y y 1 y yEXSTATy yCMDy 12? y 

Spawn PIP 

IF (DSU»LT»0) GOTO 900 
CALL WAITFR(lyDSW) 
IF (DSW.LT.O) GOTO 910 
WRITE <5y25) EXST AT ( 1 ) ♦ AND ♦ " 377 ! 

! byte of 



message 

WILL SPAWN PIP' ) 
DSW ) 



Branch on dir error 
Wait for task to exit 
Branch on dir error 
Display low 
exit status 



FORMAT <' SPAWN REPORTING ♦ PIP EXITED* EXIT 

1STATUS WAS 'ylly'.') 

CALL EXIT ! Exit 

handling code 

TYPE *y 'ERROR SPAWNING PIP. DSW = 'yDSW 
GOTO 1000 

TYPE *y 'ERROR WAITING FOR EVENT FLAG ♦ DSW 

CALL EXIT 

END 



yDSW 



Example 4-6 A Task Which Spawns PIP (Sheet 1 of 2) 
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Run Session 
>RUN SPAWN 

SPAWN IS STARTING AND WILL SPAWN PIP 

Directory DDI t C305 ? 301 3 
8-MAR-82 12: 15 

W.MAC*i 1* 20--MAY-81 .1.3:04 

A1*MACJ2 !♦ 09--DEC--80 16:58 

A*MAC?1 1. 10-JUN-81 15:21 



SPAWN ♦ MAC $22 1 ♦ 08-SEP-81 Hi 20 

Total 127 ♦/129, blocks in 25* files 

spawn reporting: pip exited* exit STATUS WAS !♦ 



>RUN SPAWN 

SPAWN IS STARTING AND WILL SPAWN PIP 

Directory DDI : C305 s> 301 2 
8-MAR-82 12:15 

bUMACJl 1. 20-MAY--81 13 J 04 

A1,MAC?2 1. 09~DEC~80 16:58 

A.MACJl 1. 10-JUN-81 15:21 

DCL> ABORT/TASK . ♦ ♦ PIP 

A9 »MAC5 12 4* 21-MAY-81 13:50 

12:i5:i5 Task "♦♦♦PIP" terminated 

Aborted via directive or CLI 
And with pending I/O reauests 

SPAWN reporting: PIP EXITED* EXIT STATUS WAS A* 



Example 4-6 A Task Which Spawns PIP (Sheet 2 of 
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Example 4-7 is a more generalized spawning task, which prompts for 
the name of a task and a command line and then spawns that task, 
sending the input command line to it. The following notes are 
keyed to the example. 

Prompt for and get the task name. The task name must be 
entered in all uppercase characters. To allow lowercase 
characters, the code must be modified to check for any 
lowercase characters and convert them to uppercase. 

Q Convert ASCII task name to Radix-50 format. 

O Prompt for and get command line. 

O Spawn task specified. We are using event flag 1 for 
synchronization. The status will be returned in EXSTAT. 

Q Wait for event flag 1 to be set, indicating that the task 
has exited (or emitted status) . 

Clear high-order byte of the status word and display it. 

Note that CLI... passes the command line to the current 
CLI (DCL) which in turn invokes task DIRT11 to display the 
directory. (This is task DIR spawned at terminal Til) 

BUFFER ( 1) and (2) are set to blanks in case a name of less 
than six characters is entered. By clearing to blanks, a 
short name is assured of having trailing blanks. 
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PROGRAM GSPAWN 
FILE GSPAWN ♦ FTN 

This task prompts at tit for a task name and command 
.'Line* then spawns the specified task and passes it the 
command line* After that it waits until the offspring 
task exits and displays its exit status 4 

Run instructions* The name of the task to he spawned 
must be typed in using all upper esse characters* 



is short 



O 

o 



REAL BUFFER ( 20 ) y TSKNAM 
INTEGER EXSTAT(8) 
C Pad task name buffer with blanks in case ri3me 
DATA BUFFER < 1 > y BUFFER ( 2 ) /' 'y' '/ 

C 

WRITE (5*15) 
FORMAT (' TASK NAME?') 
READ <5y25) BUFFER < 1 ) y BUFFER ( 2 ) 
25 FORMAT (2A4) 

C Convert task name to Radix~50 format 
£} CALL IRAD50 < 6 y BUFFER y TSKNAM ) 
WRITE (5*35) 

FORMAT (' COMMAND LINE (79 CHARACTERS OR LESS)?') 
READ (5? 45) Ny BUFFER 
45 [FORMAT <Q>20A4> 

Spawn task with command line 

CALL SPAWN < TSKNAM y y y 1 y yEXSTATy y BUFFER yNy y y IDSW) 
IF <IDSW *LT* 0) GOTO 900 ! Branch on dir error 
C Wait for task to exit 

CALL WAITFR (lylDSW) 

IF < IDSW .LT. 0) GOTO 910 ! Branch on dir error 
WRITE <5y55) EXSTAT(l) ♦ AND ♦ "377 

FORMAT < '0' ylOXy 'TASK EXITED* STATUS WAS 'yI2y'*' 
1/) 



C Error 

900 

905 



910 
915 

1000 



GOTO 1000 
code 

WRITE <5y905) IDSW 
FORMAT < ' DIRECTIVE 
1 yI4) 
GOTO 1000 

WRITE <5y915) IDSW 
FORMAT ( ' DIRECTIVE 
114) 

CALL EXIT 
END 



! Go to common exit 



ERROR SPAWNING TASK* DSW « 



ERROR ON WAIT FOR ♦ DSW 



Example 4-7 A Generalized Spawning Task (Sheet 1 of 
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Run Session 

>RUN GSPAWN 
TASK NAME? 
♦ ♦ .PIP 

COMMAND LINE (79 CHARACTERS OR LESS)? 
PIP *♦ MS/LI 

Director* DDI * C305 9 301 U 

s-sep-81 15:09 



FRIENDS ♦DIS? 2 1* 
FRIENDSNL ♦ DIS 5 2 1. 



10™ AUG -81 li:i3 
31--AUG--81 11M2 



Total of 2./10. blocks in 2. files 



TASK EXITED* STATUS WAS 1* 



>RUN GSPAWN 
TASK NAME? 

COMMAND LINE (79 CHARACTERS OR LESS)? 
DIRECTORY *.MAC 

Directory DDI : t 305 9 301 1 
O-SEP-81 15:10 



W.MAC 51 


1. 


20- 


-MAY- 


-81 


13:04 


A1.MACJ2 


1. 


09- 


-DEC- 


-80 


16:58 


A ♦ MAC 9 1 


1. 


10- 


-JUN- 


-81 


15:21 


A9.MAC r 12 


4. 


21- 


-MAY- 


-81 


13:50 


FORMAT. MAC 9 34 


6. 


21- 


-AUG- 


-81 


li:53 


PROGY.MAC? 1 


1. 


30- 


-JAN- 


-81 


14:27 


PR0GZ.MAC51 


1. 


30- 


-JAN- 


-81 


14:30 


RAY .MAC 51 


4. 


30- 


-JAN- 


-81 


14:39 


PROGX.MAC5 6 


1. 


30 


-JAN- 


-81 


14M2 


C ♦ MAC 9 5 


1 . 


21 


-MAY- 


-81 


10:01 


A2.MAC52 


1. 


21- 


-MAY- 


-81 


10:04 


C2.MAC51 _ 


1. 


21 


-MAY- 


-81 


10:04 



T3sk "DIRT11" terminated 
Aborted via directive or CLI 
And with pending I/O reauests 



TASK EXITED. STATUS WAS 4. 



Example 4-7 A Generalized Spawning Task (Sheet 2 of 2) 
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Directives Issued by an Offspring Task 

Table 4-9 summarizes the directives which can be used by an 
'offspring to return status to a parent task. Table 4-6 shows the 
standard exit status codes used on the system. An offspring can 
also spawn or connect to other tasks as well. 



Table 4-9 Directives Which Return Status 
to a Parent Task 



Directive 



Effect/Use 



CALL EXIT 



CALL EXST(status) 



Exits and returns "Success" status 
to all current parent tasks. 

Special case of CALL EXST 

Exits and returns specified one- 
word status to all current parent 
tasks . 



CALL EMST 

(pa rent- task , status ,dsw) 



Terminates parent/offspring 
relationship . 

Emit specified status to specified 
parent (or to all parents, if 
parent task name is omitted) . 

Terminates the parent/offspring 
relationship. The connection can 
be reestablished by the parent, 
using the Connect Directive. 



NOTE 

The Executive returns "Severe Exit" status if 
the task is aborted or if a fatal error 
occurs . 
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Chaining of Parent/Offspring Relationships 

An offspring can chain or pass its parent/offspring connection on 
to another task. In that case the connection between the parent 
and the offspring which passes the connection is broken. In its 
place, a connection is made between the parent and the new 
offspring. 

Figure 4-2 shows the difference between an offspring spawning 
another task versus chaining its connection to another task. Note 
that with spawn, the connection between the parent and the first 
offspring still exists, plus a new connection is established 
between the first offspring and the new offspring. 

Table 4-10 summarizes the directives which can be used to chain 
parent/offspring relationships. Request and Pass Offspring 
Information (RPOI) is similar to Spawn in function, in that it 
starts up the task and can pass a 79 byte command line. Send 
Data, Request, and Pass Offspring Control Block (SDRP) is similar 
to Send Data, Request and Connect, in that it sends a 13 word data 
packet and it succeeds even if the task is already active. 
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TASK 2 
SPAWNS 
TASK 3 



TASK 2 REQUESTS 
AND PASSES OFFSPRING 
INFORMATION 



BEFORE 



TASK 1 



TASK 2 



AFTER 



BEFORE 



AFTER 



TASK 1 



TASK 1 



TASK 2 



TASK 1 



TASK 2 



TASK 2 



TASK 3 



TASK 3 



NOTE: EACH ARROW SHOWS A PARENT/OFFSPRING CONNECTION. 
THE ARROW STARTS AT THE PARENT AND POINTS TO THE OFFSPRING. 



Figure 4-2 Spawning Versus Chaining 
(Request and Pass Offspring Information) 
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Table 4-10 Directives Which Pass Parent/Offspring 
Connections to Other Tasks 



Characteristic 


RPOI 


SDRP 


can oe usee ror a 
new offspring which 
is not yet active 


Yes 


Yes 


Can be used for a 
new offspring which 
is already active 


No, unless 
the offspring 
is CLI 


Yes 


Can pass data (or a 
command) to a new 
offspring 


Yes (up to 
79 bytes) 


Yes (13 words) 


Can be used to pass 
commands to a CLI 


Yes 


No 
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Example 4-8 shows the use of the Request and Pass Offspring 
Information (RPOI) directive. This task is similar to example 
4-6, but it uses RPOI instead of SPAWN. Two run sessions are 
provided, showing the difference between an offspring passing its 
parent/task connection and an offspring spawning another 
offspring. In the first run session, GSPAWN spawns PASSIT 
(Example 4-8) , which starts up PIP, passing its connection 
(GSPAWN/PASSIT) on to PIP. In the second run session, GSPAWN 
spawns SPAWN (Example 4-6) , which spawns PIP. Note that with 
PASSIT, ...PIP returns its exit status directly to GSPAWN. GSPAWN 
is no longer connected to PASSIT once the connection is passed on 
to PIP. With SPAWN, ...PIP returns its exit status to SPAWN. 
SPAWN displays that status and then exits, sending its own exit 
status to GSPAWN. 

The following notes are keyed to the example. 

Q Use RPOI instead of SPAWN. No event flag is needed nor is 
a status block set up since this task won't receive status 
from ...PIP. The seventh argument in the argument list 
(MACRO symbolic name RP.OAL, suggested FORTRAN name RPOAL) 
determines what parent (fixed) connections are passed, if 
any. If RPOAL has a value of 1, as in the example, all 
connections are passed. (In this example there is only 
one connection.) A connection is established between the 
parent of PASSIT (GSPAWN) and ...PIP. The connection 
between GSPAWN and PASSIT is broken. 

Q Display a message and exit with a status of 10., to make 
it easy to tell whether the status is from this task or 
from ...PIP. Note in SPAWN that the CALL EXIT is used, 
which results in a Success Code (+1) being sent as the 
exit status. 

On the First Run Session (GSPAWN spawns PASSIT) - The exit 
status from ...PIP is returned directly to GSPAWN. 

Q On the Second Run Session (GSPAWN spawns SPAWN) - The exit 
status from ...PIP is returned to SPAWN, then SPAWN 
returns its own exit status to GSPAWN. 

If you wish to chain the connection from only one of several 
parents, specify a single task, and do not specify RPOAL in the 
RPOI directive call. 

If RPOAL is not specified and no task is specified, then no 
connections are passed. This might be useful to request a task 
and send 79 bytes of data when a connection is not needed. 
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C 

C File 
C 

C This 
C disF-1 
C par en 
C 

C Data 



PROGRAM PASS IT 
PASSIT *FTN 

program requests PIP* passes it a command line to 
aw a directory at TlJy and passes it all of its 
t connections as well 



C Code 
.1.5 

O 

25 O 

C Error 
900 



INTEGER PLISTO) »DSW 

BYTE BUFF<80) 

REAL PIP»CMD<3> 

DATA PIP/6R. ♦ .PIP/ 

DATA CMD/'PIP ' » ' # ♦ MA ' * ' C/L I ' / 

WRITE <5>15) ! Write message 

FORMAT (' PASSIT IS STARTING AND WILL REQUEST PIP' 

CALL RPOI <PIP» ft »CMDfl2»lr» v t ?DSW) ! Reauest PIP 

.IF <DSW*LT*0) GOTO 900 ! Branch on dir error 

WRITE (5»25> ! Write message 

FORMAT (' PASSIT REQUESTED PIP AND WILL NOW EXIT') 

CALL EXST <10) ! Exit with status of 10 

handling code 

TYPE *y "ERROR REQUESTING PIP* DSW * '*DSW 

CALL EXIT 

END 



Example 4-8 An Offspring Task Which Chains Its 
Parent/Offspring Connection to PIP (Sheet 1 of 3) 
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Run Session 



>INS PASS IT 
>RUN GSPAWN 
TASK NAME? 
PASS IT 

COMMAND LINE (7? CHARACTERS OR LESS)? 



PASSIT IS STARTING AND WILL REQUEST PIP 
PASSIT HAS REQUESTED PIP AND WILL NOW EXIT 

Directory DDI * £305*3013 
B-MAR-82 15*22 



W.MACS1 1. 20-MAY-81 13t04 

Al*MACi2 !♦ 09-DEC-80 16:58 



SPAWN ♦ MAC 5 1 4* 08-SEP-S1 13 J 32 

Total of 13 */66* blocks in 15* files 



TASK EXITED* STATUS WAS !♦ 



>RUN GSPAWN 
TASK NAME? 
PASSIT 

COMMAND LINE <7? CHARACTERS OR LESS)? 



PASSIT IS STARTING AND WILL REQUEST PIP 
PASSIT HAS REQUESTED PIP AND WILL NOW EXIT 

Directory OBI X C305y3013 
8-SEP-81 15:23 

W.MACJl 1* 20-MAY-81 13:04 

A1.MACS2 1* 09-DEC-80 16:58 

A*MAC?1 1* 10-JUN-81 15:21 

A9.MACJ12 4» 21-MAY-81 13:50 
15:24:10 Task "♦♦♦PIP" terminated 

Aborted via directive or CLI 
And with pending I/O requests 

O TASK EXITED ♦ STATUS WAS 4* 



Example 4-8 An Offspring Task Which Chains Its 
Parent/Offspring Connection to PIP (Sheet 2 of 3) 
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Run Session 



>INS SPAWN 
>RUN GSPAWN 
TASK NAME? 
SPAWN 

COMMAND LINE (79 CHARACTERS OR LESS)? 
SPAWN IS STARTING AND WILL SPAWN PIP 

Di rectora DB1 J C305 ? 301 3 
8-MAR-82 15:22 

W ♦MAC? 1 1* 20-MAY-81 13: 04 

A.1. ♦ MAC ? 2 1* 09-DEC-80 16 J 58 



♦ 

SPAWN * MAC? 1 4* 08-SEP-81 13*32 

Total of 13*/66* blocks in 15* files 



SPAWN REPORTING* PIP EXITED? EXIT STATUS WAS 1* 
TASK EXITED* STATUS WAS 1* 



>RUN GSPAWN 
TASK NAME? 
SPAWN 

COMMAND LINE (79 CHARACTERS OR LESS)? 

SPAWN IS STARTING AND WILL SPAWN PIP 

D i recto ry DDI ♦ C305 ? 301 .:i 
B-SEP-81 15 ♦ 23 

W*MAC?1 1* 20--MAY-81 13*04 

A1*MAC?2 1* 09-DEC-80 16*58 

A.MAC? 1 1* 10-JUN-81 15 J 21 

DCL> ABORT/TASK * * * P I P 

A9.MACJ12 4* 21-MAY-81 13J50 

.1.5*24*10 Task ■♦♦♦PIP" terminated 

Aborted vis directive or CLI 
And with pending I/O requests 
"SPAWN REPORTING ♦ PIP EXITED? EXIT STATUS WAS 4* 

TASK EXITED. STATUS WAS !♦ 



Example 4-8 An Offspring Task Which Chains Its 
Parent/Offspring Connection to PIP (Sheet 3 of 3) 
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Other Parent/Offspring Considerations 



Retrieving Command Lines in Spawned Tasks - Use the Get MCR 

Command Line directive (GETMCR) • The passed command is returned 
to a buffer specified in the GETMCR call. 



Spawning a Utility or Other MCR Spawnable Task - Utilities are 
generally installed under task names of the form ...tsk. This 
makes them MCR spawnable tasks, which notifies MCR to spawn 
multiple copies of the task under names tskTnn if the task is 
invoked as an MCR command using the three-character task name 
(e.g., PIP /LI). In fact, any task is spawnable, but only tasks 
installed under a name of this form are spawned as multiple copy 
tasks by MCR. When such a task is invoked by MCR, MCR passes it 
the entire command line, including the three-character task name 
(e.g., PIP /LI). Even if you spawn a utility directly, you should 
pass a command line which includes the three-character task name. 
This maintains compatibility with the format used by MCR to pass 
commands to utilities, and avoids potential problems caused when 
the utility parses your command line. 

On RSX-11M systems, there is more likelihood of getting a task 
already active failure if you spawn a utility directly using the 
name ...tsk than there is if you instead spawn MCR... and pass 
the command line which includes the task name. This is due to the 
fact that if a task is spawned directly using ...tsk, the spawn 
attempt fails if the task ...tsk is aready active. No attempt is 
made to install the task under the name tskTnn if ...tsk is 
already active, as is the case if you spawn MCR... (MCR) to start 
up the utility. 
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Example 4-9 shows a spawned task which retrieves a simple command 
line of the form SPW n, where n is a single character. If n=l, 
SPW performs a simple addition exercise and displays the answer. 
If n=2, SPW performs a simple multiplication exercise instead. 
Else, SPW displays the message "NO OTHER OPERATIONS ALLOWED". 
This task, like most system utilities, will run correctly whether 
spawned directly by a task (as ...SPW), started by MCR as the 
result of a command line sent when spawning MCR, or invoked by an 
operator using an MCR command. 

The following notes are keyed to Example 4-9. 

O CALL GETMCR to get the command line. 

Q Display the command line as received. 

Q Check the value of n for an ASCII 1, skipping over the 
characters SPW and the blank after SPW. Note that in a 
real application, the first part of the command line 
should be checked as well to see that it really is SPW and 
a blank. Branch if not equal. 

O Check n for an ASCII 2. If not branch to error at 7. 

O If n=l, perform a simple addition (2+5). 

Q If n=2, perform a simple multiplication (2x5) . 

O !f n is neither a 1 nor a 2, display an error message and 
exit with warning status (0). 

O If n was 1 or 2, display a message giving the results of 
the computation and then exit with success status (+1). 

O This run session shows ...SPW being spawned three times by 
MCR, when an operator types an MCR command line. 

Q This run session shows ...SPW being invoked three times by 
running GSPAWN, which in turn spawns ...SPW. 
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PROGRAM SPWNED 
File SPWNED ♦FIN 

This task uses the 6ETMCR directive to sJet a command 
line from either TI* or the parent task* It then 
echoes the command line and does an add or multiply* 
types out the answer and emits status on exit 

Task-hu i 1 d i ns t r uct i ons * 

>LINK/MAP SPWNED y LB* CI y 1 3PR0GSUBS/LIBRARY y FOROTS- 
/~>LIBRARY 

Install and run instructions* To make this task MCR 
spawnabley install it under the name »* t SPW* Command 
lines should be of the form SPW function ~ valid 
functions are 1 and 2* 

BYTE INBUFF<80) 
INTEGER I0SB<2)yDSW 
INTEGER NUMlyNUM2yANS 
DATA NUMlyNUM2/5y2/ 
BYTE OP 



10 
C 

15 

C 



CALL GETMCR< INBUFFyDSW) 
IF <DSW,GT*0> GOTO 10 
TYPE *y'DIDN"T GET COMMAND 
TYPE .1.5 y (INBUFF(I) yl^lyDSW) 



! Get command line 

LINE* DSW * ' yDSW 
! Display the 
! command line 



Check 

CI 



FORMAT (lXySOAl) 
for function If branch if not 
IF (INBUFF<5) .NE. '1' ) GOTO 20 
©ANS « NUM1 + NUM2 ! 
W 0P = ' + ' ! 
GOTO 30 ! 



Do addition 
Set operation sidn 
Display results 
and exit 



C 

20 



Check for function 2y branch if not 
O IF < INBUFF<5) *NE* '2' ) GOTO 40 
©ANS = NUM1 * NUM2 ! 



30 
35 

C 
C 

40 

C 



OP = '*' 
TYPE 35yNUMl yOPyNUM2y ANS 
FORMAT (lXy.TlylXyAly I2y ' 
CALL EXST(l) 



! Do multiplication 
! Set operation sisSn 
! Display results 
yI2y ' ♦ ' ) 
! Exit with success 
! status 



Display no 
TYPE 
C AL. L. 

END 



op message 
*y ' NO OTHER 
EXST<0) 



OPERATIONS ALLOWED ' 

! Exit with 
! status 



warning 



Example 4-9 A Spawned Task Which Retrieves a 
Command Line (Sheet 1 of 2) 
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Run Session 

>ins/task_.name: ♦ ♦ ♦spw spwned 

>MCR SPW .1 
SPW 1 

5+2=7* 
>MCR SPW 2 
SPW 2 

5 * 2 = 10* 
>MCR SPW 3 
SPW 3 

NO OTHER OPERATIONS ALLOWED 



© 



>RUN GSPAWN 
TASK NAME? 
♦ ♦ *SPW 

COMMAND LINE (79 CHARACTERS OR LESS)? 
SPW .1 
SPW 1 

5+2=7. 

TASK EXITED* STATUS WAS 1* 
>RUN GSPAWN 
TASK NAME? 
♦ ♦ ♦ SPW 

COMMAND LINE (79 CHARACTERS OR LESS)? 
SPW 2 
SPW 2 

5*2= 10* 

TASK EXITED* STATUS WAS 1* 
>RUN GSPAWN 
TASK NAME? 
♦ * *SPW 

COMMAND LINE (79 CHARACTERS OR LESS)? 
SPW 3 
SPW 3 

NO OTHER OPERATIONS ALLOWED 

TASK EXITED* STATUS WAS 0* 



Example 4-9 A Spawned Task Which Retrieves a 
Command Line (Sheet 2 of 2) 



156 



USING DIRECTIVES FOR INTERTASK COMMUNICATION 



Task Abort Status - When establishing a parent/offspring 
connection, it is possible to request a second word of status when 
a task exits. In that case, the second word of the status block 
returns the task abort status. This word allows a parent task to 
distinguish the different reasons for return of "Severe Error" 
status. 

Table 4-11 lists the various task abort status codes. To get the 
second status word, place any nonzero value in the high byte of 
the event flag argument word. To do this, specify the logical OR 
of 256 and the event flag number. 

Example: 

CALL SPAWN (TASKS, , , , , 256. OR. 12, , STAT , CMD, LCMD) 





Table 


4-11 Task 


Abort Status Codes 






Exit 




Mnemonic 


Value 


Status 


Meaning 


S.CEXT 


-2(10) 


EX$SUC=1 


Task exited normally 


S.COAD 





EX$SEV=4 


Odd address and traps to 4 


S.CSGF 


2(10) 


EX$SEV 


Segment fault 


S.CBPT 


4 (10) 


EX$SEV 


Break point or trace trap 


S.CIOT 


6 (10) 


EX$SEV 


IOT instruction 


S.CILI 


8 (10) 


EX$SEV 


Illegal or reserved instruction 


S.CEMT 


10(10) 


EX$SEV 


Non RSX EMT instruction 


S.CTRP 


12(10) 


EX$SEV 


Trap instruction 


S.CFLT 


14 (10) 


EX$SEV 


11/40 floating-point exception 


S.CSST 


16(10) 


EX$SEV 


SST abort - bad stack 


S.CAST 


18 (10) 


EX$SEV 


AST abort - bad stack 


S.CABO 


20(10) 


EX$SEV 


Abort via directive or CLI command 


S.CLRF 


22(10) 


EX$SEV 


Task load request failure 


S.CCRF 


24 (10) 


EX$SEV 


Task checkpoint read failure 


S. IOMG 


26 (10) 


EX$SEV 


Task exit with outstanding I/O 


S . PRTY 


28 (10) 


EX$SEV 


Task memory parity error 


S.CPMD 


30 (10) 


EX$SEV 


Task aborted with PMD request 


S.CINS 


32(10) 


EX$SEV 


Task installed in two different 



systems 
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Summary of Various Methods of Data Transfer Between Tasks 

Table 4-12 summarizes and compares the various methods of data 
transfer between tasks which we have discussed so far. 



Comparison of Methods of Data Transfer 



Table 4-12 Comparison of Methods of Data 
Transfer Between Tasks 



Direction/ 





Maximum 


Repetition 


Pool 




Method 


Amount 


Restrictions 


Requirements 


Notes 


Send/ 


13(10) 


None 


Data packet 


Both tasks must 


Receive 


words 




is buffered 


be written to 








in pool 


use Send/Receive 










directives 


Spawn 


79(10) 


Parent to 


Command line 


Used with any 


Command 


bytes 


offspring 


is buffered 


task which uses 


Line 




only 


in pool 


GETMCR directive 










or Get Command 






Offspring 


Offspring 


Line (GCML) 






must exit 


Control Block 


routine 






for parent 


(OCB) is 








to pass 


created in 








another 


pool 








command 






Off- 


1 or 2 


Offspring 


Only OCB 


No separate 


spring 


words 


to parent 


is in pool 


directive 


Status 




only 


needed in 










parent to 






Parent must 




receive status 






reconnect to 










offspring to 




Any exiting task 






receive status 


automatically 






again 




returns status 
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Other Methods of Transferring or Sharing Data Between Tasks 

If large amounts of data are to be transferred between tasks or 
shared between tasks, two other techniques are available. Tasks 
can use files on mass storage devices. This technique is 
advantageous if really quick transfer is not essential and/or if a 
permanent copy of the data is desired. 

Tasks can also be written to share a data area in memory. This 
technique is particularly useful if transfer time is critical and 
a permanent copy of the data is either not needed at all or is not 
needed until a later time. Both of these techniques are discussed 
in later modules. 

Now do the tests/exercises for this module in the Tests/Exercises 
book. They are all lab problems. Check your answers against the 
solutions provided, either in that book or in on-line files. 

If you think that you have mastered the material, ask your course 
administrator to record your progress in your Personal Progress 
Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, return 
to this module for further study. 
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MEMORY MANAGEMENT CONCEPTS 



INTRODUCTION 

The use of memory management hardware in mapped systems permits 
the use of more physical memory, task relocation, and the sharing 
of data and code. It also offers a memory protection feature. 
This module explains how the memory management hardware works and 
how the software interacts with the hardware. Later modules 
explain the use of memory management for overlays and shared 
regions. 



OBJECTIVES 

1. To list the differences between mapped and unmapped 
systems 

2. To list the advantages of memory management 

3. To use virtual and physical addresses, windows, and 
regions to describe the mapping of a task. 



RESOURCES 

1. RSX-11M/M-PLUS Task Builder Manual , Chapter 2 

2. PDP-11 Processor Handbook, Chapter 6 (optional) 
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GOALS OF MEMORY MANAGEMENT 

The KT-11 memory management unit is a device available on medium 
and larger PDP-ll's. While the 16-bit addressing structure of the 
PDP-ll's limits processors without a memory management unit to 32K 
words of addressing, processors with a memory management unit can 
support up to 128K words, or even as much as 2000K words (2 Meg 
words) , depending on the model of the processor. 

In addition to this extension of the processor's addressing space, 
a memory management unit offers other features not otherwise 
available. With memory management, tasks can be loaded and 
executed at different locations in memory without being modified 
in any way. This means that the operating system can load a task 
into any available space within a system-controlled partition; 
therefore a task need not wait until a specific location is 
available. It also means that the Executive can move tasks around 
to make better use of available space (shuffling). 

Memory management also provides a mechanism for controlling tasks' 
access to memory. Memory areas can be protected: unrelated tasks 
can reside in memory simultaneously and are normally prevented 
from accessing each other's memory. However, tasks which do need 
to share memory locations are allowed to do so, under the rules of 
memory access built into the Executive. 



HARDWARE CONCEPTS 



Mapped Versus Unmapped Systems 

A system which has the KT-11 memory management unit installed and 
enabled is called a mapped system. Otherwise, it is called an 
unmapped system. Small PDP-ll's, such as the PDP-11/03 and 
PDP-11/04 are always unmapped. The KT-11 unit is available as an 
option on some medium sized processors, including the PDP-11/35 
and PDP-11/40. It is a standard feature on large and newer 
processors such as the PDP-11/70, PDP-11/24, PDP-11/23-PLUS and 
PDP-11/44. 

Table 5-1 shows a comparison of unmapped and mapped systems on 
various PDP-ll's. 
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Table 5-1 Mapped Versus Unmapped Systems 



System 


Addressing 


Memory 
Size 


Other 

Addressing 


Addressing 
Limit 


Unmapped 


16-bit 


28K words 


I/O page 


177777 






(56K bytes) 


4K words 


32K words 








(8K bytes) 


(64K bytes) 


Mapped 


lo-Dlt 


iz4K words 


I/O page 


T7TTT7 
////// 






(248K bytes) 


4K words 


128K words 








(8K bytes) 


(256K bytes) 


Mapped 


22-bit 


1920K words 


I/O page 


17777777 






(3840K bytes) 


4K words 


2048K words 








(8K bytes) 


(4096K bytes) 








UNIBUS map 










124K words 










(248K bytes) 





Figures 5-1 to 5-3 show physical address space on the various 
systems. Appendix B contains a conversion chart between decimal 
and octal, and between various word and byte values, which may be 
helpful as you read this module. 

Figure 5-1 shows the layout of an unmapped system. Sixteen-bit 
addresses are all that are allowed. This corresponds to an 
addressing limit of 32K words or 64K bytes. Of this, 28K words 
correspond to actual physical memory and 4K words correspond to 
the I/O page. The addresses in the I/O page are assigned to 
peripheral devices which are used in performing I/O operations. 
On an RSX-11M system, the Executive, including the Dynamic Storage 
Region (DSR or POOL) , takes up something less than or equal to 20K 
words (as little as 8K words) . Tasks occupy the area between the 
top of the Executive and the top of memory. 

Figure 5-2 shows the layout of a mapped system with 18-bit 
addressing. Eighteen bits give an addressing limit of 128K words 
or 256K bytes. Again, the top 4K words correspond to the I/O 
page, leaving 124K words of physical memory. The Executive, 
including POOL, usually takes either 16K words or 20K words, 
leaving the rest, either 108K words or 104K words, for tasks. 
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Figure 5-3 shows the layout of a mapped system with 22-bit 
addressing. Twenty-two bits give an addressing limit of 2048K 
words or 4096K bytes. Again, the top 4K words correspond to the 
I/O page. 124K words are used for UNIBUS mapping, which is needed 
when peripheral devices access memory directly (DMA devices) . 
UNIBUS mapping is necessary to convert 18-bit UNIBUS addresses to 
22-bit physical memory addresses. This leaves 1920K words of 
physical memory. Again, the Executive, including POOL, usually 
takes 16K words or 20K words, leaving 1904K words or 1900K words 



for tasks. 



4K WORDS 



{ 



(28-N)K WORDS < 



28K WORDS 
OF 

MEMORY 



N K WORDS 
(N<20) 



I/O PAGE 



TASK 
AREA 



DSR 
EXECUTIVE 



PHYSICAL 
ADDRESSES 
(IN OCTAL) 

177777 



160000 
157777 



32K WORDS 

OF ADDRESSING 



Figure 5-1 Physical Address Space in an Unmapped System 
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4K WORDS < 



108KOR 
104K WORDS 



124K WORDS 
OF 

MEMORY 



16K OR 20K 
WORDS 



I/O PAGE 



TASK 
AREA 



_ DSR 

EXECUTIVE 



PHYSICAL 
ADDRESSES 
(IN OCTAL) 

777777 



760000 
757777 



128K WORDS 
OF ADDRESSING 



Figure 5-2 Physical Address Space in an 18-Bit Mapped System 
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4K WORDS < 



124K WORDS < 



1920K 

WORDS OF i 
MEMORY 



1904KOR 
1900K WORDS 



16KOR 20K 
WORDS 



I/O PAGE 



RESERVED 
(UN I BUS MAP) 



TASK 
AREA 



DSR 



EXECUTIVE 



PHYSICAL 
ADDRESSES 
(IN OCTAL) 

17777777 

17760000 
17757777 



17000000 
16777777 



2048K WORDS 
OF ADDRESSING 



Figure 5-3 Physical Address Space in a 22-Bit Mapped System 
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Virtual and Physical Addresses 

Virtual addresses are used within a task itself. They are always 
16-bit addresses in the range 0(8) to 177777(8), or 32K words. 
When a task is task-built, virtual addresses are assigned 
typically starting at 0(8) at the beginning of the task. 

Physical addresses are used in physical memory, the I/O page, and, 
with 22-bit systems only, the UNIBUS map. They begin with 0(8) at 
the beginning of memory and include all of physical memory, the 
UNIBUS map, and the I/O page. 

On an unmapped system, no address relocation is performed. 
Therefore, virtual addresses match physical addresses. Figure 5-4 
shows a task's virtual addresses and the corresponding physical 
addresses in an unmapped system. The task is loaded beginning at 
physical address 60000(8), and addresses referenced in the task 
code reference physical addresses directly. 

On a mapped system, the memory management hardware translates or 
"maps" a task's virtual addresses to the physical addresses in 
physical memory where the task is actually loaded. In the 
simplest case, the virtual addresses are offsets from a base 
physical address where the task is loaded. If a task is later 
relocated to another location in physical memory, the virtual 
addresses are then offset from the new base physical address. 

Figure 5-5 shows a task loaded at two different locations. As 
shown below, at time 1, virtual address 1534(8) in the task is at 
the location 425134(8) in physical memory. At time 2, virtual 
address 1534(8) in the task is at location 141534(8) in physical 
memory. Since all addresses are converted at execution time, 
references to location 1534(8) in the task are resolved correctly 
regardless of where the task is loaded in physical memory. 

243400(8) Base physical address 

1534(8) Offset (task virtual address) 



425134(8) Actual physical address 

140000(8) Base physical address 

1534(8) Offset (task virtual Address) 



141534(8) Actual physical address 
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On a mapped system, the Task Builder fixes a task's code in 
virtual address space, but the actual mapping of virtual addresses 
to physical addresses is performed at run time by the memory 
management unit. Tasks may be loaded at different physical 
addresses and still run correctly. As you will see later, mapping 
also allows a task to access several separate pieces of physical 
memory. 



VIRTUAL 
ADDRESSES 
(IN OCTAL) 

137777 



VIRTUAL 
MEMORY 



TASK 

8K WORDS 



100000 



PHYSICAL 
MEMORY 



TASK 

8K WORDS 



|DSR_ 



PHYSICAL 
ADDRESSES 
(IN OCTAL) 



140000 
137777 



100000 
77777 



EXECUTIVE 

16K WORDS 





TK-7759 



Figure 5-4 Virtual Addresses Versus Physical Addresses 

on an Unmapped System 
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^ R n T D U c A c^ c VIRTUAL 

ADDRESSES 

(IN OCTAL) MEMORY 
137777 



TASK 

24K WORDS 



VIRTUAL 
MEMORY 



137777 



TASK 

24K WORDS 



PHYSICAL 
MEMORY 



KT-11 

M.M. 

UNIT 



TASK 

24K WORDS 



DSR 



EXEC 
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PHYSICAL 
ADDRESSES 
(IN OCTAL) 



403400 
403377 



243400 
243377 



120000 
117777 



TIME 1 



PHYSICAL PHYSICAL 

ADDRESSES 
MEMORY (IN OCTAL) 



KT-11 

M.M. 

UNIT 



\ 



\ 



TASK 

24K WORDS 



DSR 



EXEC 

20K WORDS 



300000 
277777 



140000 
137777 
120000 
117777 



TIME 2 



Figure 5-5 Virtual Addresses Versus Physical Addresses 

on a Mapped System 
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The KT-1 1 Memory Management Unit 



Mode Bits - Bits 15 and 14 and bits 13 and 12 of the processor 
status word (PSW) indicate, respectively, the current and previous 
modes of processor operation. The mode may be: 

• Kernel mode (00) 

• User mode (11) 

• Supervisor mode (01). (Supervisor mode is not used on 
RSX-11M, and is available only on 11/45, 11/55, 11/44, and 
11/70.) 

The purpose of having different processor modes is to provide for 
a privileged mode (kernel) where the Executive can execute 
privileged instructions (e.g., HALT), and can manipulate 
privileged locations (e.g., PSW), and a non-privileged and 
protected mode (user) where tasks usually execute. 

Active Page Registers (APRs) - The Active Page Registers (APRs) in 
the KT-11 memory management unit are used to define the mapping or 
correspondence between virtual and physical addresses. On an 
RSX-11M system, one set of eight APRs is used at a time to define 
this mapping. There is one set of APR's used for each processor 
mode; one is used in user mode and another set is used in kernel 
mode. 

At any given time, the set of APRs in use is determined by the 
mode bits in the processor status word. Each APR in the set in 
use maps a specific range of virtual addresses, as shown in Table 
5-2. The APR can map zero words, if not in use, up to the full 4K 
words, always in even multiples of 32 words. In actuality, the 
hardware may contain additional sets of APRs, but they are not 
used under RSX-11M. 

Each APR consists of two 16-bit registers, a page address register 
(PAR) and a page descriptor register (PDR) . The page address 
register contains a base address used in mapping the appropriate 
range of virtual addresses. 
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Table 5-2 APR and Virtual Address Correspondence 



APR 
Number 



Virtual Address 
Range 



K Words 



7 
6 
5 
4 
3 
2 
1 




160000-177777 (8) 
140000-157777 (8) 
120000-137777 (8) 
100000-117777 (8) 
60000- 77777(8) 
40000- 57777(8) 
20000- 37777(8) 



0- 17777 (8) 



28-32K 
24-28K 
20-24K 
16-20K 
12-16K 
8-12K 
4- 8K 
0- 4K 



Because the page address register contains only 16 bits, but the 
actual physical addresses on the larger PDP-11 *s contain 18 or 22 
bits, the 16 bits cannot contain an actual physical address. 
Instead, the 16 bits contain a block number, which corresponds to 
the high-order 16 bits (12 bits with 18-bit addressing) of the 
actual physical address. A block of memory is 32(10) words (= 
64(10) bytes = 100(8) bytes) long and starts on a 100(8) boundary. 
Therefore, the base physical address 00134200(8) is the start of 
block number 001342(8) and the base address 12445700(8) is the 
start of block number 124457(8). 

To obtain the block number from a physical address which ends in 
at least two octal zeros, just strip off the last two zeros from 
the actual address. To obtain the physical address from the block 
number, append two zeros to the end of the block number in octal. 

The page descriptor register (PDR) contains information about the 
page of memory in use, such as the length of the page (up to 4K 
words) and the access rights (read/write, read-only, etc.). The 
fields for length and access rights in the PDR provide the 
capability for hardware memory protection. If any reference in a 
task is beyond the actual area in use or violates the access 
rights, a memory protect violation is reported. 

For a more complete description of the PARs and the PDRs , see 
Chapter 6 of the PDP-11 Processor Handbook . 

Figure 5-6 shows the values in the page address registers for an 
example task. The main part of the task is 14K words long; 
therefore it needs four APRs; three APRs (APR 0,1, and 2) mapping 
4K words each, and a fourth APR (APR3) mapping the last 2K words. 
The base physical address of the task is 00432400(8), which is 
obtained by converting the block number 004324(8) to a byte 
address. 
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All virtual addresses within the main task area are mapped to 
physical addresses beginning at location 00432400(8). This means 
in effect that each virtual address corresponds to an offset from 
location 00432400(8), The page descriptor registers, not 
illustrated, indicate that APRs 0, 1, and 2 map 4K words each, but 
that APR 3 maps only 2K words. 



VIRTUAL 
MEMORY 




PHYSICAL physical 
MEMORY ADDRESSES 

(IN OCTAL) 



RESIDENT COMMON 



TASK 
AREA 



1532200 



512400 
472400 
452400 
432400 



Figure 5-6 Page Address Registers Used in Mapping a Task 
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The task in Figure 5-6 is also mapped to a resident common. APR 7 
is used to map this 4K word area, beginning at location 0153200(8) 
in physical memory. Therefore, virtual addresses from 160000(8) 
to 177777(8) map to physical addresses 01532200(8) to 01732177(8). 
Virtual address 1653414(8) corresponds to physical address 
01532200(8) + [1653414(8)-160000(8)] = 01605614(8). 

Note that a task can be loaded into a minimum of one or a maximum 
of eight separate contiguous areas of memory, because each APR 
must map to a contiguous area of memory. If a 32K word task is 
loaded into one large contiguous area, eight APRs are still used, 
but each APR maps only part of the large contiguous area. 



Converting Virtual Addresses to Physical Addresses 

The following two examples show how the KT-11 memory management 
unit converts virtual addresses to physical addresses for the task 
shown in Figure 5-6. 



Example 1 

The KT-11 unit takes a virtual address and uses the value in the 
appropriate APR to convert it to a physical address. The virtual 
address range indicates which APR to use (Table 5-2) . 

Since 053422(8) is in the range 040000-057777, APR 2 is used. Or, 
looking at the address in binary, the high-order three bits 
indicate which APR to use. Bits through 12 indicate the 
displacement or offset from the base physical address of the page. 
This is equal to 053422(8) - 040000(8) = 13422(8), the distance of 
this virtual address from the base virtual address for this APR. 

Active 



Page Displacement 
Field Field 
+ + + 

053422(8) =|010|10111000100 10| (2) 

+ + + 

2 13422(8) 
APR Offset 
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In easier terms, virtual address 40000(8) will be located at the 
base physical address. A virtual address 13422(8) bytes above 
that will be 13422(8) bytes above that physical location. The 
base physical address is determined by converting the block number 
in APR 2, 004724(8), to the physical address 00472400(8). (Recall 
that a block of memory is 100(8) bytes.) Therefore, address 
053422(8) is mapped to the location shown below. 

00472400(8) Base physical address 
+ 13422(8) Displacement 



00506022(8) Actual physical address 



Example 2 

Convert the virtual address 165275(8) 



+ + ■ + 

165275(8) =|111|0101010111101| (2) 

+ + + 

7 05275(8) 
APR Offset 



APR 7 = 015322(8) blocks = 01532200(8) Base physical address 

+ 05275(8) Displacement 



01537475(8) Actual physical address 



The memory management unit performs this conversion using an adder 
and a number of internal registers. The conversion is performed 
at extremely fast speeds. Chapter 6 of the 

PDP-11 Processor Handbook discusses this conversion process in 
more detail. 
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Virtual Address Windows 

A virtual address window, or simply a window, is a contiguous 
range of virtual addresses within a task. A window is always 
mapped as a unit, to a contiguous range of physical locations. A 
task which resides in a single contiguous area of physical memory 
generally has a single window, called the task window, which is 
mapped to the area. An example of this was shown in Figure 5-5, 
which has a single window 24K words long. Notice that the window 
is the same at time 1 and time 2, but it maps to different 
locations in physical memory. On the other hand, a task which 
must access two separate pieces of physical memory at the same 
time would have two windows (as in Figure 5-6) to map those areas. 

Windows are mapped using APRs. A virtual address window always 
corresponds to at least one, but possibly more than one, APR (up 
to all eight) . A window always begins at a 4K word boundary, 
corresponding to the lowest address mapped by the first APR used 
for the window. Successively higher APRs are then used, until the 
entire window is provided for. The Task Builder assigns most 
virtual addresses and creates most windows, determining which APRs 
will be used during that task's execution. 

The task window for a task begins at virtual address (therefore 
using APR 0) and extends upward as far as necessary to accommodate 
the task's header, stack, main code and data. Other windows can 
begin at any 4K word boundary above the high limit of the task 
window. Typically, additional windows are assigned from the top 
of virtual address space working downwards. For example, if an 
additional address window of 4K words or less is needed, it is 
assigned a base address of 160000(8), using APR 7. 

If, on the other hand, a window is needed between 4K words and 8K 
words in size, the window will be given a base address of 
140000(8). In this case, the window would use APRs 6 and 7. 
Additional windows would be assigned lower base addresses that 
correspond to other available APRs. 

NOTE 

Under no circumstance can two windows exist 
at the same time within a task using the same 
APR or the same virtual addresses. 
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The Task Builder allocates space in the task header for the 
windows it has created and records information that specifies how 
these windows are to be mapped. This information is used to load 
the APRs with appropriate values before the task executes. 

Memory management directives can be used to create and initialize 
additional windows while a task executes. Space for these 
additional windows must be allocated in the task header at 
task-build time, using the "WNDWS" option. Memory management 
directives and their use are discussed in Module 8 on Dynamic 
Regions. 



Regions 

A region is a contiguous area of physical memory to which a task 
may get access rights. A region must be contained completely 
within a partition. It can be part of a partition or the entire 
partition. 

There are three types of regions in an RSX-11M system. 

1. Task region - an area in a user-controlled partition or a 
system-controlled partition into which a task is loaded 
and then executes. 

2. Static Common Region - an area in a common type partition; 
e.g., a shared common for data or a shared library for 
code . 

3. Dynamic Region - an area in a system-controlled partition 
which is created dynamically, at run time, using the 
memory management directives. 

A task gets access rights to a region by "attaching" to the 
region. Before the Executive attaches a task to a region, it 
checks its needed access against the protection on the region. 
This is similar to checking file protection- before allowing file 
access. If the task passes the check on access rights, then the 
Executive attaches the task to the region by establishing a 
connection between the two. The total amount of physical memory, 
made up of regions, to which a task is attached is called a task's 
logical address space. 
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After a task is attached to a region, it actually accesses or uses 
the region by first "mapping" one of its virtual address windows 
to a part or to all of the region. During this process, the 
Executive uses the window and region information to fill in the 
APRs. After this, references in the task to virtual addresses in 
that window map to physical addresses within the region. A region 
does not have to be the same size as a window. Generally it is of 
equal or larger size than the window. 

Attaching and mapping are done automatically by the Executive for 
regions linked to at task-build time. Alternatively, a task can 
use memory management directives at run time to dynamically create 
regions, attach to regions, and map windows to regions. 

Figure 5-7 shows a task which has three virtual address windows 
mapped to three different regions. Figure 5-8 shows the same task 
after it attaches to another region (the work area) and maps to 
it. Notice that virtual addresses beginning at 100000(8) are used 
to map this region. For example, this area might be used as a 
temporary work buffer. Figure 5-8 does not include the actual PAR 
values or the actual physical addresses. This simpler form of 
mapping diagram will be used from now on in this course to make 
things easier, unless the actual PAR values and physical addresses 
are significant to the discussion. 

Now do the tests/exercises for this module in the Tests/Exercises 
book. They are all written problems. Check your answers against 
those provided in that book. 

If you think that you have mastered the material, ask your course 
administrator to record your progress in your Personal Progress 
Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, return 
to this module for further study. 
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WINDOW 




PHYSICAL 
MEMORY 



LIBRARY 



COMMON 



TASK 
REGION 



PHYSICAL 
ADDRESSES 
(IN OCTAL) 



1476400 



605600 



543200 



Figure 5-7 A Task with Three Windows Mapped to Three Regions 
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Figure 5-8 Task in Figure 5-7 after Attaching to and Mapping 

to a Fourth Region 
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